From 61d684b8985c683f58980155978fb1a2392e0541 Mon Sep 17 00:00:00 2001 From: Adson Rodrigues Date: Tue, 30 Jun 2026 14:26:30 -0300 Subject: [PATCH 1/2] docs: paridade pt-br (base) + nivelar idiomas MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit pt-br é a base canônica. Traz pro pt-br os guias que só existiam em en/es (documentam endpoints reais) e nivela a estrutura: - Cria pt-br: guides/{signup,balance,spei-cash-in,spei-cash-out,transactions-list}, endpoints/signup, index.mdx (landing). Traduzidos do en (contrato já correto). - Nav: adiciona os 5 guias ao grupo Guia/Guide dos 3 idiomas; +sandbox-testing no en (faltava); +endpoint signup no pt-br (grupo Cadastro). - Remove quickstart (en/es) — duplicava get-started; conserta os links pra get-started. - Remove endpoints/spei-transaction (3 idiomas + nav) — órfão (path removido do openapi). Co-Authored-By: Claude Opus 4.8 (1M context) --- ai-tools/cursor.mdx | 2 +- docs.json | 27 ++++- en/endpoints/spei-transaction.mdx | 3 - en/guides/authentication.mdx | 2 +- en/guides/quickstart.mdx | 76 -------------- en/index.mdx | 2 +- es/endpoints/spei-transaction.mdx | 3 - es/guides/authentication.mdx | 2 +- es/guides/quickstart.mdx | 76 -------------- es/index.mdx | 2 +- pt-br/endpoints/signup.mdx | 5 + pt-br/endpoints/spei-transaction.mdx | 3 - pt-br/guides/balance.mdx | 115 +++++++++++++++++++++ pt-br/guides/signup.mdx | 145 +++++++++++++++++++++++++++ pt-br/guides/spei-cash-in.mdx | 126 +++++++++++++++++++++++ pt-br/guides/spei-cash-out.mdx | 132 ++++++++++++++++++++++++ pt-br/guides/transactions-list.mdx | 119 ++++++++++++++++++++++ pt-br/index.mdx | 60 +++++++++++ 18 files changed, 730 insertions(+), 170 deletions(-) delete mode 100644 en/endpoints/spei-transaction.mdx delete mode 100644 en/guides/quickstart.mdx delete mode 100644 es/endpoints/spei-transaction.mdx delete mode 100644 es/guides/quickstart.mdx create mode 100644 pt-br/endpoints/signup.mdx delete mode 100644 pt-br/endpoints/spei-transaction.mdx create mode 100644 pt-br/guides/balance.mdx create mode 100644 pt-br/guides/signup.mdx create mode 100644 pt-br/guides/spei-cash-in.mdx create mode 100644 pt-br/guides/spei-cash-out.mdx create mode 100644 pt-br/guides/transactions-list.mdx create mode 100644 pt-br/index.mdx diff --git a/ai-tools/cursor.mdx b/ai-tools/cursor.mdx index 4e7eb93..c331886 100644 --- a/ai-tools/cursor.mdx +++ b/ai-tools/cursor.mdx @@ -233,7 +233,7 @@ Example of accordion groups: Example of cards and card groups: - + Complete walkthrough from installation to your first API call in under 10 minutes. diff --git a/docs.json b/docs.json index a09e423..1e8596c 100644 --- a/docs.json +++ b/docs.json @@ -44,6 +44,11 @@ "pages": [ "es/guides/get-started", "es/guides/authentication", + "es/guides/signup", + "es/guides/balance", + "es/guides/spei-cash-in", + "es/guides/spei-cash-out", + "es/guides/transactions-list", "es/guides/sandbox-testing", "es/guides/postman-collections" ] @@ -78,7 +83,6 @@ "es/endpoints/generate-token", "es/endpoints/spei-cash-in", "es/endpoints/spei-cash-out", - "es/endpoints/spei-transaction", "es/endpoints/webhooks-config-list", "es/endpoints/webhooks-config-setup", "es/endpoints/webhooks-config-delete" @@ -99,6 +103,12 @@ "pages": [ "en/guides/get-started", "en/guides/authentication", + "en/guides/signup", + "en/guides/balance", + "en/guides/spei-cash-in", + "en/guides/spei-cash-out", + "en/guides/transactions-list", + "en/guides/sandbox-testing", "en/guides/postman-collections" ] }, @@ -132,7 +142,6 @@ "en/endpoints/generate-token", "en/endpoints/spei-cash-in", "en/endpoints/spei-cash-out", - "en/endpoints/spei-transaction", "en/endpoints/webhooks-config-list", "en/endpoints/webhooks-config-setup", "en/endpoints/webhooks-config-delete" @@ -154,6 +163,11 @@ "pages": [ "pt-br/guides/get-started", "pt-br/guides/authentication", + "pt-br/guides/signup", + "pt-br/guides/balance", + "pt-br/guides/spei-cash-in", + "pt-br/guides/spei-cash-out", + "pt-br/guides/transactions-list", "pt-br/guides/sandbox-testing", "pt-br/guides/postman-collections" ] @@ -181,6 +195,12 @@ "pt-br/guides/webhooks/refund-out" ] }, + { + "group": "Cadastro", + "pages": [ + "pt-br/endpoints/signup" + ] + }, { "group": "Autenticação", "pages": [ @@ -191,8 +211,7 @@ "group": "SPEI", "pages": [ "pt-br/endpoints/spei-cash-in", - "pt-br/endpoints/spei-cash-out", - "pt-br/endpoints/spei-transaction" + "pt-br/endpoints/spei-cash-out" ] }, { diff --git a/en/endpoints/spei-transaction.mdx b/en/endpoints/spei-transaction.mdx deleted file mode 100644 index f3b6136..0000000 --- a/en/endpoints/spei-transaction.mdx +++ /dev/null @@ -1,3 +0,0 @@ ---- -openapi: get /api/spei/transaction/{externalId} ---- diff --git a/en/guides/authentication.mdx b/en/guides/authentication.mdx index cf69ed7..7f7c4a8 100644 --- a/en/guides/authentication.mdx +++ b/en/guides/authentication.mdx @@ -114,7 +114,7 @@ async function getToken(): Promise { ## Next Steps - + Full flow (signup → token → transaction) diff --git a/en/guides/quickstart.mdx b/en/guides/quickstart.mdx deleted file mode 100644 index edd40e0..0000000 --- a/en/guides/quickstart.mdx +++ /dev/null @@ -1,76 +0,0 @@ ---- -title: 'Quickstart' -description: 'Signup, authentication and first SPEI transaction' ---- - -## Prerequisites - -- `clientId` and `clientSecret` (obtained via `POST /api/signup` or from the panel) -- X.509 certificate (mTLS) provided by NTX Pay -- HTTPS URL to receive webhooks - -## 1. Create account - -```bash -curl -X POST https://sandbox.mx.ntxpay.com/api/signup \ - -H "Content-Type: application/json" \ - -d '{ - "email": "maria@example.com", - "holderName": "Maria Lopez", - "entityType": "OTHER", - "isSandbox": true - }' -``` - -The response includes `credentials.clientId` and `credentials.clientSecret`. The `clientSecret` is shown only once. - -## 2. Generate token - -```bash -ENCODED_CERT=$(cat client.cert.pem | python3 -c "import sys,urllib.parse; print(urllib.parse.quote(sys.stdin.read()))") - -curl -X POST https://sandbox.mx.ntxpay.com/api/auth/token \ - -H "X-SSL-Client-Cert: $ENCODED_CERT" \ - -H "Content-Type: application/json" \ - -d '{"clientId":"qr-93-550e8400","clientSecret":"a1b2..."}' -``` - -Returns `access_token` with 10-minute validity. - -## 3. Configure webhook - -```bash -curl -X POST https://sandbox.mx.ntxpay.com/api/webhooks-config \ - -H "Authorization: Bearer $TOKEN" \ - -H "Content-Type: application/json" \ - -d '{ - "url": "https://my-server.com/webhooks/ntxpay", - "events": ["cash_in"] - }' -``` - -The response includes the `secret` used to validate the HMAC signature. - -## 4. Create SPEI charge - -```bash -curl -X POST https://sandbox.mx.ntxpay.com/api/spei/cash-in \ - -H "Authorization: Bearer $TOKEN" \ - -H "Content-Type: application/json" \ - -d '{ - "amountCentavos": 50000, - "externalId": "order-001", - "customerName": "Juan Perez" - }' -``` - -Returns `destinationClabe`. The payer transfers to that CLABE; confirmation arrives via webhook `cash_in`. - -## Environments - -| Environment | URL | Provider | -|---|---|---| -| Sandbox | `https://sandbox.mx.ntxpay.com` | `sandbox` (simulated transactions) | -| Production | Provided at onboarding | `smartfastpay` | - -Sandbox account: `isSandbox: true` in signup. diff --git a/en/index.mdx b/en/index.mdx index 362aa7d..986f235 100644 --- a/en/index.mdx +++ b/en/index.mdx @@ -41,7 +41,7 @@ ISO 8601 UTC: `2026-05-12T14:31:05.000Z`. ## First steps - + Signup, token and first transaction diff --git a/es/endpoints/spei-transaction.mdx b/es/endpoints/spei-transaction.mdx deleted file mode 100644 index f3b6136..0000000 --- a/es/endpoints/spei-transaction.mdx +++ /dev/null @@ -1,3 +0,0 @@ ---- -openapi: get /api/spei/transaction/{externalId} ---- diff --git a/es/guides/authentication.mdx b/es/guides/authentication.mdx index a233950..0bb83b1 100644 --- a/es/guides/authentication.mdx +++ b/es/guides/authentication.mdx @@ -114,7 +114,7 @@ async function getToken(): Promise { ## Próximos Pasos - + Flujo completo (signup → token → transacción) diff --git a/es/guides/quickstart.mdx b/es/guides/quickstart.mdx deleted file mode 100644 index fa179b2..0000000 --- a/es/guides/quickstart.mdx +++ /dev/null @@ -1,76 +0,0 @@ ---- -title: 'Quickstart' -description: 'Signup, autenticación y primera transacción SPEI' ---- - -## Prerrequisitos - -- `clientId` y `clientSecret` (obtenidos vía `POST /api/signup` o desde el panel) -- Certificado X.509 (mTLS) proporcionado por NTX Pay -- URL HTTPS para recibir webhooks - -## 1. Crear cuenta - -```bash -curl -X POST https://sandbox.mx.ntxpay.com/api/signup \ - -H "Content-Type: application/json" \ - -d '{ - "email": "maria@example.com", - "holderName": "Maria Lopez", - "entityType": "OTHER", - "isSandbox": true - }' -``` - -La respuesta trae `credentials.clientId` y `credentials.clientSecret`. El `clientSecret` se muestra una única vez. - -## 2. Generar token - -```bash -ENCODED_CERT=$(cat client.cert.pem | python3 -c "import sys,urllib.parse; print(urllib.parse.quote(sys.stdin.read()))") - -curl -X POST https://sandbox.mx.ntxpay.com/api/auth/token \ - -H "X-SSL-Client-Cert: $ENCODED_CERT" \ - -H "Content-Type: application/json" \ - -d '{"clientId":"qr-93-550e8400","clientSecret":"a1b2..."}' -``` - -Retorna `access_token` con validez de 10 minutos. - -## 3. Configurar webhook - -```bash -curl -X POST https://sandbox.mx.ntxpay.com/api/webhooks-config \ - -H "Authorization: Bearer $TOKEN" \ - -H "Content-Type: application/json" \ - -d '{ - "url": "https://mi-servidor.com/webhooks/ntxpay", - "events": ["cash_in"] - }' -``` - -La respuesta trae el `secret` usado para validar la firma HMAC. - -## 4. Crear cobro SPEI - -```bash -curl -X POST https://sandbox.mx.ntxpay.com/api/spei/cash-in \ - -H "Authorization: Bearer $TOKEN" \ - -H "Content-Type: application/json" \ - -d '{ - "amountCentavos": 50000, - "externalId": "order-001", - "customerName": "Juan Perez" - }' -``` - -Retorna `destinationClabe`. El pagador transfiere a esa CLABE; la confirmación llega vía webhook `cash_in`. - -## Ambientes - -| Ambiente | URL | Provider | -|---|---|---| -| Sandbox | `https://sandbox.mx.ntxpay.com` | `sandbox` (transacciones simuladas) | -| Producción | Provista en el onboarding | `smartfastpay` | - -Cuenta sandbox: `isSandbox: true` en el signup. diff --git a/es/index.mdx b/es/index.mdx index 74aa249..11e195d 100644 --- a/es/index.mdx +++ b/es/index.mdx @@ -41,7 +41,7 @@ ISO 8601 UTC: `2026-05-12T14:31:05.000Z`. ## Primeros pasos - + Signup, token y primera transacción diff --git a/pt-br/endpoints/signup.mdx b/pt-br/endpoints/signup.mdx new file mode 100644 index 0000000..4729384 --- /dev/null +++ b/pt-br/endpoints/signup.mdx @@ -0,0 +1,5 @@ +--- +title: 'Signup' +description: 'Criação de conta NTX Pay México (sandbox ou produção)' +openapi: post /api/signup +--- diff --git a/pt-br/endpoints/spei-transaction.mdx b/pt-br/endpoints/spei-transaction.mdx deleted file mode 100644 index f3b6136..0000000 --- a/pt-br/endpoints/spei-transaction.mdx +++ /dev/null @@ -1,3 +0,0 @@ ---- -openapi: get /api/spei/transaction/{externalId} ---- diff --git a/pt-br/guides/balance.mdx b/pt-br/guides/balance.mdx new file mode 100644 index 0000000..c7d6d02 --- /dev/null +++ b/pt-br/guides/balance.mdx @@ -0,0 +1,115 @@ +--- +title: 'Consulta de Saldo' +description: 'Saldo disponível e pendente da conta em centavos MXN' +--- + +## Visão Geral + +O endpoint `GET /api/balance` retorna o saldo da conta autenticada em **centavos MXN** (inteiros). Há dois campos: + +- **`availableCentavos`** — saldo disponível para enviar cash-out SPEI +- **`pendingCentavos`** — saldo bloqueado (cash-out em processamento, cash-in confirmando) + +## Endpoint + +### GET /api/balance + +#### Headers + +``` +Authorization: Bearer {token} +``` + +#### Request + +```bash +curl -X GET https://sandbox.mx.ntxpay.com/api/balance \ + -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." +``` + +#### Response (200) + +```json +{ + "availableCentavos": 4873490, + "pendingCentavos": 0, + "currency": "MXN" +} +``` + +`4873490` centavos = **$48.734,90 MXN**. + +## Estrutura da Resposta + + + Saldo disponível em centavos MXN. Use este valor para validar antes de um cash-out. + + + + Saldo pendente em centavos MXN. Inclui cash-out em processamento e cash-in aguardando a confirmação final do provedor. + + + + Sempre `MXN` no escopo México. + + +## Exemplo em Node.js + +```typescript +import axios from 'axios'; + +async function getBalance(token: string) { + const { data } = await axios.get('https://sandbox.mx.ntxpay.com/api/balance', { + headers: { Authorization: `Bearer ${token}` }, + }); + + const availableMXN = (data.availableCentavos / 100).toFixed(2); + const pendingMXN = (data.pendingCentavos / 100).toFixed(2); + + console.log(`Available: $${availableMXN} MXN`); + console.log(`Pending: $${pendingMXN} MXN`); + return data; +} +``` + +## Validação Antes do Cash-Out + +```typescript +async function safeSpeiCashOut(amountCentavos: number, token: string, dto: any) { + const balance = await getBalance(token); + + if (balance.availableCentavos < amountCentavos) { + throw new Error( + `Insufficient balance: available ${balance.availableCentavos}, ` + + `requested ${amountCentavos} (in centavos)`, + ); + } + + return axios.post('https://sandbox.mx.ntxpay.com/api/spei/cash-out', dto, { + headers: { Authorization: `Bearer ${token}` }, + }); +} +``` + + + Mesmo validando o saldo antes, o cash-out pode falhar com `400` se outro cash-out concorrente consumir o saldo. Trate o erro `400` como "saldo insuficiente" no momento da chamada. + + +## Códigos de Resposta + +| Código | Significado | +|---|---| +| `200` | Saldo consultado | +| `401` | Token inválido ou ausente | +| `502` | `account-ms` indisponível | + +## Próximos Passos + + + + Envie uma transferência SPEI usando o saldo disponível + + + Veja o histórico de movimentações + + diff --git a/pt-br/guides/signup.mdx b/pt-br/guides/signup.mdx new file mode 100644 index 0000000..fd886d2 --- /dev/null +++ b/pt-br/guides/signup.mdx @@ -0,0 +1,145 @@ +--- +title: 'Signup' +description: 'Criação programática de conta NTX Pay México (sandbox ou produção)' +--- + +## Visão Geral + +O endpoint `POST /api/signup` cria uma nova conta NTX Pay México. **Não requer autenticação** (sem JWT, sem certificado) — é a porta de entrada da integração. + +Na criação, a NTX Pay: + +1. Provisiona a conta no Keycloak (provedor de identidade) +2. Aplica limites e tarifas padrão +3. Define o `mainProvider`: + - `sandbox` se `isSandbox=true` (padrão — transações simuladas, self-service) + - `smartfastpay` caso contrário (produção — **não** é self-service; exige onboarding de KYC com o time) +4. Emite credenciais OAuth 2.0 (`clientId` + `clientSecret`) +5. Opcionalmente emite certificado mTLS + +## Endpoint + +### POST /api/signup + +#### Request — Pessoa física (sandbox) + +```bash +curl -X POST https://sandbox.mx.ntxpay.com/api/signup \ + -H "Content-Type: application/json" \ + -d '{ + "email": "maria@example.com", + "holderName": "Maria Lopez", + "entityType": "OTHER", + "phone": "+5215512345678", + "isSandbox": true + }' +``` + + + No sandbox, o `holderTaxIdPrimary` (RFC) é opcional — se omitido, um RFC de teste único é gerado automaticamente. + + +#### Request — Pessoa jurídica (`SA_CV` / `SAPI_CV`) + +```bash +curl -X POST https://sandbox.mx.ntxpay.com/api/signup \ + -H "Content-Type: application/json" \ + -d '{ + "email": "contact@acme.mx", + "holderName": "Acme S.A. de C.V.", + "entityType": "SA_CV", + "razonSocial": "Acme S.A. de C.V.", + "holderTaxIdPrimary": "ACM850101AB1", + "isSandbox": true + }' +``` + +#### Response (201) + +```json +{ + "accountId": 93, + "publicId": "acc_550e8400-e29b-41d4-a716-446655440000", + "mainProvider": "sandbox", + "credentials": { + "clientId": "qr-93-550e8400", + "clientSecret": "a1b2c3d4e5f6g7h8" + }, + "certificate": { + "fingerprint": "sha256:abcd1234...", + "expiresAt": "2027-05-13T00:00:00.000Z" + }, + "message": "Account created successfully. Store clientSecret in a safe place." +} +``` + + + O `clientSecret` é exibido **uma única vez**, na resposta do signup. Se perdido, é necessário emitir uma nova credencial pelo painel ou contatando o suporte. + + +## Campos do Request + + + E-mail de contato — torna-se o login do portal (owner). + + + + Nome / razão social do titular da conta (mínimo 3, máximo 255 caracteres). + + + + Tipo de pessoa jurídica mexicana: `SAPI_CV`, `SA_CV` ou `OTHER`. `SAPI_CV` e `SA_CV` exigem `razonSocial`. + + + + Razão social. **Obrigatório** quando `entityType` é `SAPI_CV` (sufixo "S.A.P.I. de C.V.") ou `SA_CV` (sufixo "S.A. de C.V."). Opcional para `OTHER`. + + + + RFC do titular (10–20 caracteres). **Opcional no sandbox**: se omitido, um RFC de teste único é gerado automaticamente. + + + + Telefone no formato E.164 (8–20 caracteres). Ex.: `+5215512345678`. + + + + Padrão **`true`** → conta sandbox self-service (provider `sandbox`, transações simuladas). + `false` → conta de produção (provider `smartfastpay`) — **não** é self-service; exige onboarding de KYC com o time. + + + + **Deprecado** — aceito mas ignorado pelo backend (o tipo de documento é sempre RFC). A classificação legal vem de `entityType`. + + + + **Deprecado** — aceito mas ignorado pelo backend. Use `entityType` no lugar. + + +## Sandbox vs Produção + +| Aspecto | Sandbox | Produção | +|---|---|---| +| Provider | `sandbox` | `smartfastpay` | +| Confirmação SPEI | Imediata (simulada) | Real (segundos a minutos via Banxico) | +| Custo | Gratuito | Tarifas em produção | +| Limites | Permissivos | Por contrato | +| Endpoint base | `https://sandbox.mx.ntxpay.com` | Fornecido no onboarding | + +## Erros Comuns + +| Código | Causa | +|---|---| +| `400` | Campo obrigatório ausente (`email`/`holderName`/`entityType`), `razonSocial` ausente para `SAPI_CV`/`SA_CV`, RFC inválido, ou tax ID já em uso | +| `502` | `account-ms` (provisionamento) indisponível — tente novamente | + +## Próximos Passos + + + + Use o clientId/clientSecret recém-emitidos para gerar o JWT + + + Boas práticas para testar no sandbox + + diff --git a/pt-br/guides/spei-cash-in.mdx b/pt-br/guides/spei-cash-in.mdx new file mode 100644 index 0000000..7289564 --- /dev/null +++ b/pt-br/guides/spei-cash-in.mdx @@ -0,0 +1,126 @@ +--- +title: 'SPEI Cash-In' +description: 'Receba pagamentos SPEI via CLABE descartável de uso único' +--- + +## Visão Geral + +O **cash-in SPEI** gera uma **CLABE descartável** que o pagador usa para fazer uma transferência SPEI pelo app do banco. Quando a NTX Pay recebe a liquidação, a transação passa para `CONFIRMED` e dispara o webhook `cash_in`. + +Características: + +- CLABE válida para uma **única** transferência (uso único) +- Confirmação **assíncrona** (segundos a minutos) +- Expira em data configurável (padrão ~24 horas) + +## Endpoint + +### POST /api/spei/cash-in + +#### Headers + +``` +Authorization: Bearer {token} +Content-Type: application/json +``` + +#### Request + +```bash +curl -X POST https://sandbox.mx.ntxpay.com/api/spei/cash-in \ + -H "Authorization: Bearer $TOKEN" \ + -H "Content-Type: application/json" \ + -d '{ + "amountCentavos": 50000, + "externalId": "order-abc-123", + "description": "Order #123", + "customerName": "Juan Perez", + "customerEmail": "juan@example.com", + "customerTaxId": "PEPJ800101ABC" + }' +``` + +#### Response (201) + +```json +{ + "id": 12345, + "status": "PENDING", + "destinationClabe": "012180001234567890", + "beneficiary": { + "name": "NTX Pay MX", + "taxId": "NTX800101ABC" + }, + "referenceNumerical": "1234567", + "checkoutUrl": "https://pay.ntxpay.com/checkout/xyz", + "expiresAt": "2026-05-14T23:59:59.000Z", + "amountCentavos": 50000 +} +``` + +## Campos do Request + + + Valor em centavos MXN (mínimo 1). Ex.: `50000` = $500,00 MXN. + + + + Identificador externo único (até 100 caracteres). Use para correlacionar com o seu sistema. Recomendado para idempotência. + + + + Descrição da cobrança (até 255 caracteres). + + + + Nome do pagador (1–255 caracteres), exibido no checkout SPEI. + + + + E-mail do pagador (formato de e-mail válido). + + + + RFC/CURP do pagador (10–20 caracteres). + + +## Fluxo de Pagamento + +```mermaid +sequenceDiagram + participant App as Sua aplicação + participant NTX as NTX Pay + participant Payer as Pagador + participant Bank as Banco do pagador + + App->>NTX: POST /api/spei/cash-in + NTX-->>App: 201 + destinationClabe + App->>Payer: Exibe CLABE (e/ou checkoutUrl) + Payer->>Bank: Transferência SPEI para destinationClabe + Bank-->>NTX: Liquidação SPEI + NTX->>App: webhook cash_in (CONFIRMED) +``` + +## Estados da Transação + +| Status | Significado | +|---|---| +| `PENDING` | CLABE emitida, aguardando transferência | +| `CONFIRMED` | Transferência recebida e liquidada | +| `FAILED` | Erro de processamento | +| `EXPIRED` | CLABE expirou sem receber transferência | + +## Idempotência + +Reenvie a mesma requisição com o mesmo `externalId` para garantir que uma falha de rede não gere duas cobranças. Em caso de duplicação, a NTX Pay retorna a cobrança existente. + +## Próximos Passos + + + + Detalhes do payload do webhook de confirmação + + + Envie transferências SPEI + + diff --git a/pt-br/guides/spei-cash-out.mdx b/pt-br/guides/spei-cash-out.mdx new file mode 100644 index 0000000..7b2e58f --- /dev/null +++ b/pt-br/guides/spei-cash-out.mdx @@ -0,0 +1,132 @@ +--- +title: 'SPEI Cash-Out' +description: 'Envie transferências SPEI para qualquer CLABE' +--- + +## Visão Geral + +O **cash-out SPEI** envia uma transferência interbancária para uma **CLABE de destino**. O saldo da conta é debitado e a NTX Pay encaminha ao provedor (`smartfastpay` em produção, `sandbox` para testes). A confirmação chega via webhook `cash_out`. + +## Endpoint + +### POST /api/spei/cash-out + +#### Headers + +``` +Authorization: Bearer {token} +Content-Type: application/json +``` + +#### Request + +```bash +curl -X POST https://sandbox.mx.ntxpay.com/api/spei/cash-out \ + -H "Authorization: Bearer $TOKEN" \ + -H "Content-Type: application/json" \ + -d '{ + "amountCentavos": 50000, + "destinationClabe": "012180001234567890", + "beneficiaryName": "Maria Lopez", + "beneficiaryTaxId": "LOMA850101ABC", + "concept": "Invoice 123 payment" + }' +``` + +#### Response (201) + +```json +{ + "id": 56789, + "status": "PENDING", + "destinationClabe": "012180001234567890", + "amountCentavos": 50000, + "referenceNumerical": "9876543", + "createdAt": "2026-05-13T12:00:00.000Z" +} +``` + +## Campos do Request + + + Valor em centavos MXN (mínimo 1). Ex.: `50000` = $500,00 MXN. + + + + CLABE de destino — **exatamente 18 dígitos numéricos** (regex: `^\d{18}$`). + + + + Nome do beneficiário (3–255 caracteres). + + + + RFC/CURP do beneficiário (10–20 caracteres). Recomendado para reconciliação. + + + + Conceito exibido no extrato do beneficiário (até 255 caracteres). + + +## Validação de Saldo + +Antes de enviar, valide o saldo: + +```typescript +const balance = await getBalance(token); +if (balance.availableCentavos < amountCentavos) { + throw new Error('Insufficient balance'); +} +``` + + + Saldo insuficiente retorna `400` — a transação **não é criada**. Aplique idempotência no lado do cliente (não reprocesse o mesmo pedido após um `400` sem revalidar o saldo). + + +## Estados + +| Status | Significado | +|---|---| +| `PENDING` | Cash-out aceito, aguardando liquidação SPEI | +| `CONFIRMED` | Liquidado no Banxico | +| `FAILED` | Rejeitado pelo provedor ou pela rede SPEI | + +## Códigos de Erro + +| Código | Causa | +|---|---| +| `400` | Saldo insuficiente, CLABE inválida, payload inválido | +| `401` | Token inválido | +| `502` | mexico-ms / provedor indisponível — não tente novamente sem verificar o status via `GET /api/transactions` | + +## Exemplo em Node.js com Retry + +```typescript +async function speiCashOut(token: string, dto: any) { + try { + const { data } = await axios.post( + 'https://sandbox.mx.ntxpay.com/api/spei/cash-out', + dto, + { headers: { Authorization: `Bearer ${token}` } }, + ); + return data; // status: PENDING + } catch (err) { + if (err.response?.status === 502) { + // Não sabemos se a transação foi criada. Consulte /api/transactions filtrando por externalId + // antes de tentar novamente. + } + throw err; + } +} +``` + +## Próximos Passos + + + + Detalhes do payload do webhook de liquidação + + + Verifique o status sem depender do webhook + + diff --git a/pt-br/guides/transactions-list.mdx b/pt-br/guides/transactions-list.mdx new file mode 100644 index 0000000..65a2aa9 --- /dev/null +++ b/pt-br/guides/transactions-list.mdx @@ -0,0 +1,119 @@ +--- +title: 'Listar Transações' +description: 'Consulte o histórico SPEI da sua conta' +--- + +## Visão Geral + +`GET /api/transactions` retorna a lista paginada de transações da conta autenticada, cobrindo **SPEI** (cash-in, cash-out, refund-in, refund-out, internal_transfer). É a fonte da verdade quando você precisa **reconciliar** ou verificar status sem depender de webhooks. + + + **Rate limit**: 30 requisições por minuto, por conta. Acima disso, `429`. + + +## Endpoint + +### GET /api/transactions + +#### Headers + +``` +Authorization: Bearer {token} +``` + +#### Query Parameters + +| Parâmetro | Tipo | Padrão | Descrição | +|---|---|---|---| +| `limit` | int (1–100) | 20 | Itens por página | +| `offset` | int (≥0) | 0 | Offset de paginação | +| `status` | enum | — | `PENDING`, `CONFIRMED`, `FAILED`, `EXPIRED` | +| `paymentMethod` | enum | — | `SPEI` | +| `direction` | enum | — | `in` (recebido), `out` (enviado) | + +#### Request + +```bash +curl -X GET "https://sandbox.mx.ntxpay.com/api/transactions?status=CONFIRMED&paymentMethod=SPEI&limit=50" \ + -H "Authorization: Bearer $TOKEN" +``` + +#### Response (200) + +```json +{ + "data": [ + { + "id": 12345, + "externalId": "order-abc-123", + "paymentMethod": "SPEI", + "direction": "in", + "type": "cash_in", + "status": "CONFIRMED", + "provider": "smartfastpay", + "amountCentavos": 50000, + "clabe": "012180001234567890", + "createdAt": "2026-05-12T14:30:00.000Z", + "confirmedAt": "2026-05-12T14:31:05.000Z" + } + ], + "metadata": { + "total": 142, + "limit": 20, + "offset": 0, + "hasMore": true + } +} +``` + +## Paginação + +Itere usando `offset` até `hasMore` ser `false`: + +```typescript +let offset = 0; +const limit = 50; + +while (true) { + const { data } = await axios.get('https://sandbox.mx.ntxpay.com/api/transactions', { + headers: { Authorization: `Bearer ${token}` }, + params: { limit, offset, status: 'CONFIRMED' }, + }); + + for (const tx of data.data) { + await process(tx); + } + + if (!data.metadata.hasMore) break; + offset += limit; +} +``` + +## Reconciliação Diária + +Padrão recomendado para o fechamento diário: + +1. Liste as transações `CONFIRMED` do dia (idealmente filtrando por `createdAt` no seu lado após o fetch) +2. Cruze cada `externalId` com o pedido correspondente no seu sistema +3. Sinalize pendências/divergências para investigação + +## Rate Limit + +O `AccountThrottlerGuard` aplica um limite **por conta** (não por IP). Ao exceder: + +```json +HTTP 429 Too Many Requests +{ "message": "ThrottlerException: Too Many Requests" } +``` + +Aguarde alguns segundos antes de tentar novamente. Em rotinas em lote, use `limit=100` para reduzir o número de chamadas. + +## Códigos de Resposta + +| Código | Significado | +|---|---| +| `200` | Lista retornada | +| `400` | Parâmetros inválidos (ex.: `limit > 100`) | +| `401` | Token inválido | +| `429` | Rate limit excedido | +| `502` | mexico-ms indisponível | diff --git a/pt-br/index.mdx b/pt-br/index.mdx new file mode 100644 index 0000000..309b044 --- /dev/null +++ b/pt-br/index.mdx @@ -0,0 +1,60 @@ +--- +title: 'API NTX Pay México' +description: 'Integração com SPEI em uma única API' +--- + +Gateway público para integração com SPEI (transferências interbancárias instantâneas). Receba e envie via SPEI, consulte saldo e transações, receba webhooks assinados. + +## Ambientes + +| Ambiente | URL | +|---|---| +| Sandbox | `https://sandbox.mx.ntxpay.com` | +| Produção | Fornecida no onboarding | + +## Autenticação + +1. `POST /api/signup` cria a conta e retorna `clientId` + `clientSecret`. +2. `POST /api/auth/token` com certificado X.509 no header `X-SSL-Client-Cert` + credenciais retorna um JWT (validade de 10 min). + +O JWT vai em `Authorization: Bearer ` nos demais endpoints. + +## Valores monetários + +Centavos MXN, inteiros. `50000` = $500,00 MXN. + +## Datas + +ISO 8601 UTC: `2026-05-12T14:31:05.000Z`. + +## Códigos HTTP + +| Código | Significado | +|---|---| +| `200` / `201` | Sucesso | +| `400` | Dados inválidos ou saldo insuficiente | +| `401` | Token ou certificado inválido | +| `404` | Recurso não encontrado | +| `429` | Rate limit | +| `502` | Provedor downstream indisponível | + +## Primeiros passos + + + + Signup, token e primeira transação + + + Cash-in e cash-out via CLABE + + + Notificações HMAC + + + Schemas por endpoint + + + +## Suporte + +`suporte@ntxpay.com` · `https://app.ntxpay.com` From 229dfa1f1c74d8b2193da1a10c3f0f4a8417b562 Mon Sep 17 00:00:00 2001 From: Adson Rodrigues Date: Tue, 30 Jun 2026 14:51:43 -0300 Subject: [PATCH 2/2] docs(nav): simetria total entre idiomas MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit en/es passam a usar os mesmos subgrupos de endpoints do pt-br (Cadastro/Autenticação/SPEI/Webhooks Config), com labels traduzidos por idioma. Estrutura idêntica nos 3 idiomas (7 grupos, mesma ordem). Co-Authored-By: Claude Opus 4.8 (1M context) --- docs.json | 52 +++++++++++++++++++++++++++++++++++++++++----------- 1 file changed, 41 insertions(+), 11 deletions(-) diff --git a/docs.json b/docs.json index 1e8596c..9e9ab5e 100644 --- a/docs.json +++ b/docs.json @@ -40,7 +40,7 @@ "tab": "API Reference", "groups": [ { - "group": "Guide", + "group": "Guía", "pages": [ "es/guides/get-started", "es/guides/authentication", @@ -65,7 +65,7 @@ ] }, { - "group": "Webhooks", + "group": "Eventos de Webhook", "pages": [ "es/guides/webhooks/overview", "es/guides/webhooks/setup", @@ -77,12 +77,27 @@ ] }, { - "group": "Endpoints", + "group": "Registro", + "pages": [ + "es/endpoints/signup" + ] + }, + { + "group": "Autenticación", + "pages": [ + "es/endpoints/generate-token" + ] + }, + { + "group": "SPEI", "pages": [ - "es/endpoints/signup", - "es/endpoints/generate-token", "es/endpoints/spei-cash-in", - "es/endpoints/spei-cash-out", + "es/endpoints/spei-cash-out" + ] + }, + { + "group": "Webhooks Config", + "pages": [ "es/endpoints/webhooks-config-list", "es/endpoints/webhooks-config-setup", "es/endpoints/webhooks-config-delete" @@ -124,7 +139,7 @@ ] }, { - "group": "Webhooks", + "group": "Webhook Events", "pages": [ "en/guides/webhooks/overview", "en/guides/webhooks/setup", @@ -136,12 +151,27 @@ ] }, { - "group": "Endpoints", + "group": "Signup", + "pages": [ + "en/endpoints/signup" + ] + }, + { + "group": "Authentication", + "pages": [ + "en/endpoints/generate-token" + ] + }, + { + "group": "SPEI", "pages": [ - "en/endpoints/signup", - "en/endpoints/generate-token", "en/endpoints/spei-cash-in", - "en/endpoints/spei-cash-out", + "en/endpoints/spei-cash-out" + ] + }, + { + "group": "Webhooks Config", + "pages": [ "en/endpoints/webhooks-config-list", "en/endpoints/webhooks-config-setup", "en/endpoints/webhooks-config-delete"