Listar locais de atendimento
/v1/locaisRetorna locais de atendimento / rede credenciada de uma operadora.
Resposta repassada como a operadora envia, sem normalização: o formato desta rota é definido por ela, e pode ser uma lista. Leia o corpo como veio.
Em homologação SulAmérica esta consulta ainda depende de liberação de acesso: a resposta traz a mensagem da operadora informando que o corretor não tem permissão para o recurso. Valide o fluxo antes de usar em produção.
Headers
X-Cnpj-Provedorstringrequired
CNPJ da operadora de destino, atua como chave de roteamento (padrão Mediator). Ex.: SulAmérica 01685053000156.
ex: 01685053000156Responses
Resposta da operadora, repassada sem alteração de formato. Pode ser uma lista, e pode conter mensagem de negócio em vez de locais.
Formato definido pela operadora; não normalizado.
Ver schema bruto / exemplo JSON
{
"description": "Formato definido pela operadora; não normalizado."
}Requisição malformada (campos obrigatórios ausentes/ inválidos).
Estrutura padronizada de erro.
Código HTTP do erro.
Código interno do erro.
Descrição legível do erro.
items
Crítica de validação devolvida pela operadora. bloqueante vem do wrapper de validacoes (mensagem "Critica Bloqueante" / "Critica Não Bloqueante"): false = aviso (a movimentação segue e pode liberar, ex. 2401); true = rejeição (corrigir e reenviar); null = a operadora não marcou.
Token ausente, expirado ou inválido.
Estrutura padronizada de erro.
Código HTTP do erro.
Código interno do erro.
Descrição legível do erro.
items
Crítica de validação devolvida pela operadora. bloqueante vem do wrapper de validacoes (mensagem "Critica Bloqueante" / "Critica Não Bloqueante"): false = aviso (a movimentação segue e pode liberar, ex. 2401); true = rejeição (corrigir e reenviar); null = a operadora não marcou.
Não foi possível concluir a operação junto à operadora.
Em consulta, sem repetir no corpo a falha pode ser transitória e nova tentativa é segura.
Em escrita (POST, PATCH, DELETE) o corpo traz repetir: false, e o desfecho é indeterminado: a operadora pode ter processado e só a resposta ter se perdido. Não reenvie. Se o corpo trouxer protocolo, consulte-o em GET /v1/movimentacoes/{protocolo}; se não, confira o beneficiário pelo CPF antes de tentar de novo.
Erro gerado pela própria API, antes ou depois de falar com a operadora. Formato distinto do Erro, que é usado quando o desfecho vem da operadora.
Motivo resumido.
Detalhe técnico, quando existe.
Quando false, não reenvie. Em consulta significa que repetir devolve o mesmo resultado; em escrita significa que o desfecho é indeterminado, porque a operadora pode ter processado e só a resposta ter se perdido. Ausente quando a falha pode ser transitória, o que só ocorre em consulta.
Protocolo da movimentação, quando a operadora devolveu um antes de falhar. **Em escrita com 502, consulte este protocolo em GET /v1/movimentacoes/{protocolo} em vez de reenviar.**
Caminho chamado na operadora, sem host. Para diagnóstico.
Resposta da operadora, para diagnóstico. Formato variável.
Outro status de transporte, repassado do provedor como veio (ex. 403, 404, 409, 429). A fachada não os traduz: mascará-los de 400 esconderia do consumidor a diferença entre pedido inválido e limite de uso, por exemplo.
Não são desfecho de negócio. Rejeição da operadora chega em HTTP 200 com criticas; ausência de registro também é 200. Um status aqui indica problema de integração, não de cadastro, e vale acionar o suporte.
Estrutura padronizada de erro.
Código HTTP do erro.
Código interno do erro.
Descrição legível do erro.
items
Crítica de validação devolvida pela operadora. bloqueante vem do wrapper de validacoes (mensagem "Critica Bloqueante" / "Critica Não Bloqueante"): false = aviso (a movimentação segue e pode liberar, ex. 2401); true = rejeição (corrigir e reenviar); null = a operadora não marcou.
Listar locais de atendimento
/v1/locaisRetorna locais de atendimento / rede credenciada de uma operadora.
Resposta repassada como a operadora envia, sem normalização: o formato desta rota é definido por ela, e pode ser uma lista. Leia o corpo como veio.
Em homologação SulAmérica esta consulta ainda depende de liberação de acesso: a resposta traz a mensagem da operadora informando que o corretor não tem permissão para o recurso. Valide o fluxo antes de usar em produção.
Headers
X-Cnpj-Provedorstringrequired
CNPJ da operadora de destino, atua como chave de roteamento (padrão Mediator). Ex.: SulAmérica 01685053000156.
ex: 01685053000156Responses
Resposta da operadora, repassada sem alteração de formato. Pode ser uma lista, e pode conter mensagem de negócio em vez de locais.
Formato definido pela operadora; não normalizado.
Ver schema bruto / exemplo JSON
{
"description": "Formato definido pela operadora; não normalizado."
}Requisição malformada (campos obrigatórios ausentes/ inválidos).
Estrutura padronizada de erro.
Código HTTP do erro.
Código interno do erro.
Descrição legível do erro.
items
Crítica de validação devolvida pela operadora. bloqueante vem do wrapper de validacoes (mensagem "Critica Bloqueante" / "Critica Não Bloqueante"): false = aviso (a movimentação segue e pode liberar, ex. 2401); true = rejeição (corrigir e reenviar); null = a operadora não marcou.
Token ausente, expirado ou inválido.
Estrutura padronizada de erro.
Código HTTP do erro.
Código interno do erro.
Descrição legível do erro.
items
Crítica de validação devolvida pela operadora. bloqueante vem do wrapper de validacoes (mensagem "Critica Bloqueante" / "Critica Não Bloqueante"): false = aviso (a movimentação segue e pode liberar, ex. 2401); true = rejeição (corrigir e reenviar); null = a operadora não marcou.
Não foi possível concluir a operação junto à operadora.
Em consulta, sem repetir no corpo a falha pode ser transitória e nova tentativa é segura.
Em escrita (POST, PATCH, DELETE) o corpo traz repetir: false, e o desfecho é indeterminado: a operadora pode ter processado e só a resposta ter se perdido. Não reenvie. Se o corpo trouxer protocolo, consulte-o em GET /v1/movimentacoes/{protocolo}; se não, confira o beneficiário pelo CPF antes de tentar de novo.
Erro gerado pela própria API, antes ou depois de falar com a operadora. Formato distinto do Erro, que é usado quando o desfecho vem da operadora.
Motivo resumido.
Detalhe técnico, quando existe.
Quando false, não reenvie. Em consulta significa que repetir devolve o mesmo resultado; em escrita significa que o desfecho é indeterminado, porque a operadora pode ter processado e só a resposta ter se perdido. Ausente quando a falha pode ser transitória, o que só ocorre em consulta.
Protocolo da movimentação, quando a operadora devolveu um antes de falhar. **Em escrita com 502, consulte este protocolo em GET /v1/movimentacoes/{protocolo} em vez de reenviar.**
Caminho chamado na operadora, sem host. Para diagnóstico.
Resposta da operadora, para diagnóstico. Formato variável.
Outro status de transporte, repassado do provedor como veio (ex. 403, 404, 409, 429). A fachada não os traduz: mascará-los de 400 esconderia do consumidor a diferença entre pedido inválido e limite de uso, por exemplo.
Não são desfecho de negócio. Rejeição da operadora chega em HTTP 200 com criticas; ausência de registro também é 200. Um status aqui indica problema de integração, não de cadastro, e vale acionar o suporte.
Estrutura padronizada de erro.
Código HTTP do erro.
Código interno do erro.
Descrição legível do erro.
items
Crítica de validação devolvida pela operadora. bloqueante vem do wrapper de validacoes (mensagem "Critica Bloqueante" / "Critica Não Bloqueante"): false = aviso (a movimentação segue e pode liberar, ex. 2401); true = rejeição (corrigir e reenviar); null = a operadora não marcou.