Construir uma integração confiável

Ler o envelope da resposta

As respostas JSON usam um formato comum. success indica êxito; code é o status; code_message resume o resultado; errors[] reúne os problemas; header traz metadados; data_count conta itens; e data é sempre uma lista, mesmo quando há um único resultado.

1{"success":true,"code":200,"code_message":"A requisição foi processada com sucesso.","errors":[],"header":null,"data_count":1,"data":[{"result":"..."}]}

Não assuma que data[0] sempre existe. Uma busca sem resultados pode retornar 200 com data: []. Confira success, data_count e o contrato da rota antes de usar o primeiro item.

Pedir metadados da chamada

Envie summary=true na query quando precisar de detalhes da execução no header, incluindo log_id, preço, cobrança e modo de execução. Guarde o log_id para suporte e conciliação com a tela Chamadas. O header HTTP X-Api4devs-Log-Id também o fornece.

Tratar erros de forma estável

Use errors[].code para decidir o que seu sistema fará. Esse identificador é estável; mensagens podem mudar ou ser traduzidas. Mostre a mensagem ao usuário quando fizer sentido, mas programe tentativas e alertas pelo código e pelo status HTTP.

Evitar execução duplicada

Para uma operação que não deve repetir, envie uma Idempotency-Key única por tentativa lógica. Repetir a mesma chave com o mesmo conteúdo devolve a resposta anterior, sem executar ou cobrar outra vez. Enquanto a primeira execução ainda está em andamento, a repetição retorna 409. Se o conteúdo mudar com a mesma chave, retorna 422.

1curl 'https://staging.apifordevs.com/api/v1/oracle/document/read?dev_mode=true' \
2  -u "afd_test_pk_...:$APIFORDEVS_TEST_SECRET" \
3  -H 'Idempotency-Key: pedido-1842' \
4  -F 'file=@documento.pdf' -F 'document_type=CNH'

Receber uma resposta binária

Algumas rotas, como recorte de rosto, retornam arquivo em vez de JSON. Leia o Content-Type para salvar o conteúdo corretamente. Os metadados da chamada vêm nos headers X-Api4devs-*; não tente interpretar os bytes como o envelope JSON.

No desenvolvimento, teste o mesmo fluxo de arquivo no Playground. Antes de automatizar, abra a referência da rota para conferir tipo de entrada, tamanho permitido e formato de saída.

Respostas rápidas

Próximos passos