{ "openapi": "3.0.3", "info": { "title": "Shortcode API", "description": "Documentação OpenAPI da API Shortcode: SMS, RCS, Voz, WhatsApp (WABA) e Links.", "version": "2.0.0" }, "servers": [ { "url": "https://api.shortcode.com.br", "description": "Produção" } ], "tags": [ { "name": "Conta", "description": "Saldo e dados da conta" }, { "name": "SMS", "description": "Envio SMS e blacklist" }, { "name": "RCS", "description": "Envio RCS, modelos/templates e webhooks da conta" }, { "name": "VOZ", "description": "Templates e envio de voz" }, { "name": "WABA", "description": "WhatsApp Business API" }, { "name": "LINKS", "description": "Links encurtados, WhatsApp e rotativos" } ], "components": { "securitySchemes": { "BearerAuth": { "type": "http", "scheme": "bearer", "description": "Token Bearer da conta Shortcode" } } }, "paths": { "/account/balance": { "get": { "tags": ["Conta"], "summary": "Consultar saldo da conta", "description": "Retorna saldo em R$ (conta unificada) ou créditos short. Não consome saldo.", "security": [{ "BearerAuth": [] }], "responses": { "200": { "description": "Saldo atual", "content": { "application/json": { "examples": { "saldo_unico": { "value": { "saldo_unico": true, "saldo": 1523.45, "moeda": "BRL" } }, "creditos": { "value": { "saldo_unico": false, "saldo_short": 9400, "unidade": "creditos" } } } } } } } } }, "/messages": { "post": { "tags": ["SMS"], "summary": "Enviar SMS", "security": [{ "BearerAuth": [] }], "requestBody": { "content": { "application/json": { "example": [{ "external_id": "001", "number": "41999999999", "message": "Olá!" }] } } }, "responses": { "201": { "description": "Mensagens processadas" } } } }, "/blacklist": { "get": { "tags": ["SMS"], "summary": "Listar blacklist", "security": [{ "BearerAuth": [] }], "responses": { "200": { "description": "Lista de números bloqueados" } } }, "post": { "tags": ["SMS"], "summary": "Inserir na blacklist", "security": [{ "BearerAuth": [] }], "requestBody": { "content": { "application/json": { "example": [{ "telefone": "41999999999", "motivo": "Opt-out" }] } } }, "responses": { "201": { "description": "Números inseridos" } } }, "delete": { "tags": ["SMS"], "summary": "Remover da blacklist", "security": [{ "BearerAuth": [] }], "requestBody": { "content": { "application/json": { "example": [{ "telefone": "41999999999" }] } } }, "responses": { "200": { "description": "Números removidos" } } } }, "/rcs/messages": { "post": { "tags": ["RCS"], "summary": "Enviar mensagens RCS", "security": [{ "BearerAuth": [] }], "requestBody": { "content": { "application/json": { "examples": { "text": { "summary": "Texto simples", "value": [{ "external_id": "rcs_001", "numero": "5511999999999", "agente_id": 7, "tipo": "text", "mensagem": "Olá!", "fallback_sms": "Olá! (SMS)" }] }, "media": { "summary": "Mídia (imagem/vídeo)", "value": [{ "external_id": "rcs_media_001", "numero": "5511999999999", "agente_id": 7, "tipo": "media", "media_url": "https://exemplo.com/imagens/promo.jpg", "mensagem": "Confira nossa promoção!", "fallback_sms": "Confira nossa promoção: https://exemplo.com" }] }, "card": { "summary": "Card (formato painel / carousel)", "value": [{ "external_id": "rcs_card_001", "numero": "5511999999999", "agente_id": 7, "tipo": "card", "fallback_sms": "FOCO NO RESULTADO! shortcode.com.br", "carousel": [{ "media": { "url": "https://exemplo.com/imagens/card.jpg", "contentType": "image/jpeg" }, "title": "FOCO NO RESULTADO!", "text": "Alcance mais clientes com RCS, SMS e VOZ.", "buttons": [ { "type": "url", "text": "Visite o site", "url": "https://shortcode.com.br/" }, { "type": "reply", "text": "Tenho interesse", "id": "tenho_interesse" } ] }] }] }, "carousel": { "summary": "Carousel (vários cards)", "value": [{ "external_id": "rcs_car_001", "numero": "5511999999999", "agente_id": 7, "tipo": "carousel", "fallback_sms": "Confira nossas ofertas!", "carousel": [ { "media": { "url": "https://exemplo.com/img1.jpg", "contentType": "image/jpeg" }, "title": "Oferta 1", "text": "Desconto especial", "buttons": [{ "type": "reply", "text": "Quero", "id": "oferta1" }] }, { "media": { "url": "https://exemplo.com/img2.jpg", "contentType": "image/jpeg" }, "title": "Oferta 2", "text": "Frete grátis", "buttons": [{ "type": "url", "text": "Ver mais", "url": "https://exemplo.com/oferta2" }] } ] }] }, "template_vars": { "summary": "Template com variáveis ($par1$..$par5$)", "value": [{ "external_id": "rcs_tpl_001", "numero": "5511999999999", "agente_id": 7, "tipo": "template", "template_id": 12, "par1": "João", "par2": "pedido 458", "fallback_sms": "Olá João, seu pedido 458" }] }, "template_variables_obj": { "summary": "Template com variables {}", "value": [{ "external_id": "rcs_tpl_002", "numero": "5511999999999", "agente_id": 7, "tipo": "template", "template_id": 12, "variables": { "par1": "Maria", "par2": "R$ 50", "par3": "hoje" } }] } } } } }, "responses": { "201": { "description": "Mensagens processadas — sempre verifique o status por item (accepted|failed). HTTP 201 não significa que todos foram aceitos.", "content": { "application/json": { "examples": { "accepted": { "summary": "Aceita", "value": [{ "external_id": "rcs_001", "numero": "11999999999", "status": "accepted", "message_id": "rcs.9d6f9cba342abcdef", "operadora": "Vivo" }] }, "failed": { "summary": "Falha", "value": [{ "external_id": "rcs_001", "numero": "11999999999", "status": "failed", "message_id": "rcs.308b716f14603feff530446abd2ab6ef", "operadora": "Vivo", "reason": "external_id já utilizado" }] }, "mixed": { "summary": "Misto", "value": [ { "external_id": "rcs_001", "numero": "11999999999", "status": "accepted", "message_id": "rcs.aaa111", "operadora": "Vivo" }, { "external_id": "rcs_002", "numero": "11888888888", "status": "failed", "message_id": "rcs.bbb222", "operadora": "Claro", "reason": "external_id já utilizado" } ] } } } } } } } }, "/rcs/templates": { "get": { "tags": ["RCS"], "summary": "Listar modelos RCS", "security": [{ "BearerAuth": [] }], "parameters": [ { "name": "id", "in": "query", "schema": { "type": "integer" }, "description": "ID do modelo (opcional)" } ], "responses": { "200": { "description": "Lista de templates" } } }, "post": { "tags": ["RCS"], "summary": "Criar modelo RCS", "security": [{ "BearerAuth": [] }], "requestBody": { "content": { "application/json": { "examples": { "text": { "summary": "Texto com variáveis", "value": { "nome": "Boas-vindas", "tipo": "text", "mensagem": "Olá $par1$, seu pedido $par2$ foi confirmado.", "fallback_sms": "Olá $par1$, pedido $par2$ confirmado." } }, "card": { "summary": "Card (carousel no painel)", "value": { "nome": "FOCO NO RESULTADO", "tipo": "card", "fallback_sms": "Alcance mais clientes com RCS, SMS e VOZ.", "carousel": [{ "media": { "url": "https://exemplo.com/imagens/card.jpg", "contentType": "image/jpeg" }, "title": "FOCO NO RESULTADO!", "text": "Alcance mais clientes com nossos serviços.", "buttons": [ { "type": "url", "text": "Visite o site", "url": "https://shortcode.com.br/" }, { "type": "reply", "text": "Tenho interesse", "id": "tenho_interesse" } ] }] } }, "card_objeto": { "summary": "Card via objeto card", "value": { "nome": "Card oferta", "tipo": "card", "card": { "media": { "url": "https://exemplo.com/img.jpg", "contentType": "image/jpeg" }, "title": "Oferta para $par1$", "text": "Seu cupom: $par2$", "buttons": [{ "type": "reply", "text": "Quero", "id": "quero" }] } } }, "carousel": { "summary": "Carousel", "value": { "nome": "Carousel ofertas", "tipo": "carousel", "fallback_sms": "Confira as ofertas!", "carousel": [ { "media": { "url": "https://exemplo.com/1.jpg", "contentType": "image/jpeg" }, "title": "Oferta 1", "text": "Desconto $par1$", "buttons": [{ "type": "reply", "text": "Quero", "id": "o1" }] }, { "media": { "url": "https://exemplo.com/2.jpg", "contentType": "image/jpeg" }, "title": "Oferta 2", "text": "Frete grátis", "buttons": [{ "type": "url", "text": "Ver", "url": "https://exemplo.com" }] } ] } }, "media": { "summary": "Mídia", "value": { "nome": "Banner promo", "tipo": "media", "media_url": "https://exemplo.com/banner.jpg", "mensagem": "Promoção $par1$", "fallback_sms": "Promoção $par1$" } } } } } }, "responses": { "201": { "description": "Template criado" } } }, "put": { "tags": ["RCS"], "summary": "Editar modelo RCS", "security": [{ "BearerAuth": [] }], "requestBody": { "content": { "application/json": { "example": { "id": 12, "nome": "Boas-vindas v2", "mensagem": "Oi $par1$! Pedido $par2$ OK." } } } }, "responses": { "200": { "description": "Template atualizado" } } }, "delete": { "tags": ["RCS"], "summary": "Apagar modelo RCS", "security": [{ "BearerAuth": [] }], "requestBody": { "content": { "application/json": { "example": { "id": 12 } } } }, "responses": { "200": { "description": "Template removido" } } } }, "/rcs/webhooks": { "post": { "tags": ["RCS"], "summary": "Criar webhook RCS da conta", "security": [{ "BearerAuth": [] }], "requestBody": { "content": { "application/json": { "examples": { "message_received": { "summary": "Mensagem recebida (MO)", "value": { "evento": "rcs_message_received", "url": "https://meucrm.com/hooks/rcs", "descricao": "CRM principal" } }, "delivery_report": { "summary": "DLR (relatório de entrega)", "value": { "evento": "rcs_delivery_report", "url": "https://meucrm.com/hooks/rcs-dlr", "descricao": "CRM DLR" } } } } } }, "responses": { "201": { "description": "Webhook criado" } } }, "put": { "tags": ["RCS"], "summary": "Editar webhook RCS da conta", "security": [{ "BearerAuth": [] }], "requestBody": { "content": { "application/json": { "example": { "id": 42, "url": "https://meucrm.com/hooks/rcs" } } } }, "responses": { "200": { "description": "Webhook atualizado" } } }, "delete": { "tags": ["RCS"], "summary": "Apagar webhook RCS da conta", "security": [{ "BearerAuth": [] }], "requestBody": { "content": { "application/json": { "example": { "id": 42 } } } }, "responses": { "200": { "description": "Webhook removido" } } } }, "/voz/templates": { "get": { "tags": ["VOZ"], "summary": "Listar templates de voz", "security": [{ "BearerAuth": [] }], "responses": { "200": { "description": "Lista de templates" } } } }, "/voz/messages": { "post": { "tags": ["VOZ"], "summary": "Enviar mensagem de voz", "security": [{ "BearerAuth": [] }], "requestBody": { "content": { "application/json": { "example": [{ "external_id": "voz_001", "number": "5511999999999", "template_id": 1, "variables": { "nome": "João" } }] } } }, "responses": { "201": { "description": "Envio aceito" } } } }, "/whatsapp/messages": { "post": { "tags": ["WABA"], "summary": "Enviar mensagem WhatsApp", "security": [{ "BearerAuth": [] }], "requestBody": { "content": { "application/json": { "example": [{ "external_id": "msg001", "number": "5547991170182", "canal_id": 1, "type": "text", "message": "Olá!", "fallback_sms": "Olá! (SMS)" }] } } }, "responses": { "201": { "description": "Mensagens processadas" } } } }, "/links": { "get": { "tags": ["LINKS"], "summary": "Listar links", "security": [{ "BearerAuth": [] }], "responses": { "200": { "description": "Lista de links" } } }, "post": { "tags": ["LINKS"], "summary": "Criar link", "security": [{ "BearerAuth": [] }], "requestBody": { "content": { "application/json": { "example": { "tipo": "encurtado", "url_destino": "https://meusite.com/promo", "dominio_id": 1, "keyword": "promo-verao" } } } }, "responses": { "201": { "description": "Link criado" } } }, "put": { "tags": ["LINKS"], "summary": "Editar link", "security": [{ "BearerAuth": [] }], "requestBody": { "content": { "application/json": { "example": { "id": 10, "url_destino": "https://novo.com" } } } }, "responses": { "200": { "description": "Link atualizado" } } }, "delete": { "tags": ["LINKS"], "summary": "Deletar link", "security": [{ "BearerAuth": [] }], "requestBody": { "content": { "application/json": { "example": { "id": 10 } } } }, "responses": { "200": { "description": "Link removido" } } } } } }