Fundamentos de integração da API

Configure estes aspectos compartilhados antes de integrar um recurso da API da DEUNA. As mesmas regras de ambiente, rede, repetição e tempo limite se aplicam a pedidos, pagamentos, usuários, links de pagamento e assinaturas.

Ambientes#

Sandbox e produção são isolados e usam credenciais, dados e endpoints de webhook diferentes.

Consulte Autenticação e ambientes para conhecer os tipos de credencial, a rotação e os exemplos de solicitações.

Coleção do Postman#

Use a coleção do Postman da DEUNA para explorar solicitações antes de desenvolver um cliente.

Abrir a coleção da DEUNA no Postman

1. Entre no Postman e crie um fork da coleção no seu workspace.
2. Selecione o ambiente de sandbox ou produção.
3. Configure merchant_id, public_api_keye private_api_key com os valores desse ambiente.
4. Comece por uma operação do catálogo de endpoints.

Endereços IP#

Prefira uma lista de domínios permitidos quando sua política de rede aceitar. Se o receptor de webhooks ou um provedor de pagamento ou fraude exigir uma lista de IPs permitidos, use os endereços abaixo.

Códigos de resposta#

Operações bem-sucedidas retornam uma resposta 2xx . Uma resposta 4xx significa que autenticação, permissões, dados ou estado do recurso precisam mudar. Uma resposta 5xx é uma falha temporária da DEUNA ou do provedor e só deve ser repetida quando for seguro repetir a operação.

Use a referência de respostas e códigos de erro para identificar a causa, a política de repetição e a ação corretiva.

Solicitações idempotentes#

Envie uma X-Idempotency-Key estável para cada operação distinta que crie ou altere o estado de um pagamento. Reutilize a mesma chave e o corpo idêntico ao repetir após uma falha de rede ou tempo limite do cliente. Use uma nova chave para uma nova tentativa de negócio.

X-Api-Key: YOUR_PRIVATE_API_KEY
X-Store-Code: STORE_CODE
X-Idempotency-Key: order_1042-attempt_1
Content-Type: application/json

Consulte Criar um pagamento para o contrato e o exemplo de repetição da compra.

Tempos limite do cliente#

Um tempo limite do cliente significa que ele parou de esperar; isso não prova que o pagamento falhou. O processamento pode continuar por verificações de fraude, roteamento e provedor depois da desconexão.

Quando uma solicitação de pagamento expirar:

1. Mantenha o fulfillment bloqueado e marque a tentativa como pendente de conciliação no seu sistema.
2. Preserve o ID do pedido, o corpo e a chave de idempotência original.
3. Repita apenas quando a operação for elegível, com a mesma chave e corpo idêntico.
4. Concilie o estado final por um Webhook verificado ou uma consulta de pedido adequada no catálogo de endpoints.
5. Mostre o resultado conciliado ao comprador e resolva qualquer cancelamento ou reembolso necessário antes do fulfillment.