# Xingubit Pay API

> Plataforma multi-tenant de pagamentos Pix (COB e COBV), liquidação instantânea, saque (Cashout), emissão automática de notas fiscais (NF-e, NFS-e, NFCom) e gestão financeira.

## Informações Gerais
- **Base URL:** https://pay.xingubit.com.br
- **Autenticação:** OAuth 2.0 (Bearer JWT via `POST /v1/oauth/token`)
- **Versão da API:** v1 (1.24.0)

## Documentação Técnica Completa
- [Documentação Oficial para LLMs](https://pay.xingubit.com.br/xingubit-pay-api-llms.md): Guia detalhado contendo todos os endpoints, payloads de requisição/resposta, exemplos em JSON e fluxos de integração.
- [Guia Rápido Web](https://pay.xingubit.com.br/doc): Portal web com fluxograma visual, exemplos interativos e changelog dinâmico.

## Principais Recursos & Endpoints
- **Autenticação:** `POST /v1/oauth/token`
- **Múltiplas Aplicações & Credenciais:** `POST /v1/applications`, `GET /v1/applications`, `GET /v1/applications/{id}`, `PUT /v1/applications/{id}`, `POST /v1/applications/{id}/rotate-secret`, `DELETE /v1/applications/{id}`
- **Cobranças Pix:** `POST /v1/charges` (Pix Imediato COB, Pix com Vencimento COBV, Carnê Pix Parcelado em 2x-24x, Cobranças Multi-Itens com Emissão Fiscal Híbrida NFS-e + NF-e), `GET /v1/charges/{txId}`, `GET /v1/charges` (suporta `?appId=`), `PATCH /v1/charges/{txId}`
- **Webhooks:** Notificações instantâneas de pagamento `PIX_PAID` com payload padronizado (`amount`, `valor`, `paidAt`, `e2eId`, `appId`, `metadata`). Gerenciamento via `PUT /v1/applications/{id}` ou `GET/PUT /v1/merchants/me/webhook`.
- **Cashout & Auto-Cashout:** `POST /v1/cashouts` (Saque manual sob demanda com validação de titularidade), `GET /v1/cashouts` (Histórico de transferências), `GET/PUT /v1/cashouts/config` (Rotina de sweep automático), `GET /v1/merchants/me/balance`
- **Gestão de Clientes:** `POST/GET/PUT/DELETE /v1/customers` (Com suporte a filtro `?appId=`, validação estrita Bean Validation e busca por termo)
- **Gestão de Produtos & Serviços:** `POST/GET/PUT/DELETE /v1/products` (Suporte a LC 116, NCM, CFOP, CEST e busca universal com query `?search=`)
- **Notas Fiscais Avulsas:** `POST/GET/DELETE /v1/invoices/{docType}` (`nfe`, `nfse`, `nfcom`)
- **Consulta de CEP com Georreferenciamento:** `GET /v1/cep/{cep}` (Autenticado)