Introdução

A API Multi-Pay é a API de pagamentos multi-gateway da plataforma: vendas (PIX, cartão, boleto e bolepix), links de pagamento, split, gestão de lojistas, terminais POS, serviços bancários (saldo, extrato, saque, transferência) e liquidações.

Base URL

https://api-gateway.nectaco.com.br

Todas as chamadas usam HTTPS. Requisições e respostas são application/json, salvo indicação em contrário (uploads usam multipart/form-data).

O modelo multi-gateway

Cada marketplace da plataforma aponta para um gateway de pagamento (Dock, Cappta/Getnet C ou Zoop). A API expõe um contrato único e genérico — as rotas não carregam o nome do gateway; o provider correto é resolvido a partir do marketplace do usuário autenticado.

Consequências práticas:

• O mesmo código de integração funciona para qualquer gateway.
• Alguns recursos dependem de capacidade do gateway (ex.: boleto e bolepix hoje só em marketplaces Getnet C; royalty em gateways que o expõem). Quando o gateway não suporta, a API responde 400 com mensagem explicando.
• Endpoints de repasse (ex.: recibos e overview de venda) retornam o payload bruto do gateway — o formato varia conforme o provider.

Hierarquia de recursos

Marketplace (aponta p/ um gateway; tem branding e domínio white-label)
└── Establishment / seller (lojista; tem conta bancária, plano de taxas, POS)
    └── Sales, Payment Links, Splits, Banking…

Usuários pertencem a um marketplace e, opcionalmente, a um estabelecimento — o escopo de visibilidade de cada chamada deriva desse vínculo (ver Autenticação).

Convenções

• Identificadores: todo recurso é identificado publicamente por id — um UUID. IDs numéricos internos nunca são expostos nem aceitos.
• Valores monetários: centavos inteiros (1299 = R$ 12,99), salvo indicação contrária no endpoint.
• Datas: ISO 8601 (YYYY-MM-DD ou timestamp completo). Filtros de período (startDate/endDate) devem ser enviados juntos; alguns aceitam também DD/MM/YYYY.
• Paginação: page + limit (ou perPage, indicado por endpoint); respostas paginadas incluem { currentPage, limit, total }.
• Idempotência: operações bancárias de escrita (saque, transferência interna) exigem request_id gerado pelo cliente — reenvios com o mesmo id não duplicam a operação.

Primeiros passos

1. Obtenha suas credenciais de acesso com o administrador do seu marketplace.
2. Autentique-se em POST /users/login e guarde o token JWT (ver Autenticação).
3. Faça sua primeira chamada:

curl -H "Authorization: Bearer $TOKEN" \
  "https://api-gateway.nectaco.com.br/sales/summary"

4. Consulte a Referência da API para o contrato completo de cada endpoint, e Erros para o tratamento de falhas.

Versionamento

O contrato vigente é a v1. Mudanças compatíveis (novos endpoints e campos opcionais) entram na própria v1; mudanças incompatíveis criarão uma v2 — a v1 será preservada. Todo o conteúdo é versionado via Git neste repositório.