# Xingubit Pay API - Documentação para LLMs

Esta é a documentação técnica oficial da API de pagamentos e notas fiscais da Xingubit Pay.

## 1. Autenticação (OAuth 2.0)

Todos os endpoints requerem um Bearer Token JWT. O token tem validade de 1 hora.

**Endpoint:** `POST /v1/oauth/token`
**Content-Type:** `application/x-www-form-urlencoded`

**Parâmetros (Body):**
- `client_id`: Seu Client ID
- `client_secret`: Seu Client Secret

**Resposta de Sucesso:**
```json
{
  "access_token": "eyJhb...",
  "token_type": "Bearer",
  "expires_in": "3600"
}
```

## 2. Criar Cobrança Pix

A API da Xingubit Pay é extremamente flexível. Você pode criar um Pix Imediato (Cob) simples, emitir notas fiscais junto com o Pix, ou gerar uma Cobrança com Vencimento (CobV) aplicando juros e multas.

**Endpoint:** `POST /v1/charges`
**Header:** `Authorization: Bearer {token}`
**Content-Type:** `application/json`

### Exemplo 1: Pix Imediato Simples (Sem Nota)
O formato mais enxuto para apenas gerar um QR Code Pix.

```json
{
  "paymentMethod": "PIX",
  "description": "Pagamento avulso",
  "amount": {
    "original": 150.00
  },
  "payer": {
    "name": "João da Silva",
    "document": "12345678900"
  },
  "metadata": {
    "seu_id_interno": "PEDIDO-1001"
  }
}
```

### Exemplo 2: Pix Imediato com Nota Fiscal (1 Item - Produto Cadastrado)
Gera o Pix e, assim que for pago, emite automaticamente a Nota Fiscal vinculada a um produto que o lojista já cadastrou no painel da Xingubit.

```json
{
  "paymentMethod": "PIX",
  "description": "Mensalidade do Software",
  "amount": {
    "original": 50.00
  },
  "payer": {
    "name": "Maria Souza",
    "document": "98765432100",
    "address": {
      "street": "Rua das Flores 123",
      "neighborhood": "Centro",
      "city": "São Paulo",
      "state": "SP",
      "zipCode": "01000000"
    }
  },
  "invoice": true,
  "invoiceType": "NFSE",
  "invoiceItems": [
    {
      "productId": "123e4567-e89b-12d3-a456-426614174000",
      "quantidade": 1,
      "valorUnitario": 50.00,
      "valorTotal": 50.00
    }
  ]
}
```

### Exemplo 3: Pix Imediato com Nota Fiscal (Múltiplos Itens / Dados Avulsos)
Para ERPs que enviam os impostos dinamicamente sem pré-cadastrar produtos, ou quando há mais de um item no mesmo Pix.

```json
{
  "paymentMethod": "PIX",
  "description": "Licença e Treinamento",
  "amount": {
    "original": 350.00
  },
  "payer": {
    "name": "Empresa XPTO Ltda",
    "document": "12345678000199",
    "address": {
      "street": "Av Paulista 1000",
      "neighborhood": "Bela Vista",
      "city": "São Paulo",
      "state": "SP",
      "zipCode": "01310100"
    }
  },
  "invoice": true,
  "invoiceType": "NFSE",
  "invoiceItems": [
    {
      "productId": "123e4567-e89b-12d3-a456-426614174000",
      "quantidade": 1,
      "valorUnitario": 50.00,
      "valorTotal": 50.00
    },
    {
      "descricao": "Treinamento Presencial",
      "ncm": "85235110",
      "cfop": "5101",
      "serviceCode": "01.01",
      "cnae": "6204000",
      "quantidade": 2,
      "valorUnitario": 150.00,
      "valorTotal": 300.00
    }
  ]
}
```

### Exemplo 4: Pix com Vencimento (CobV com Juros, Multa e Desconto)
Apenas enviando o bloco `calendar`, o motor roteia para um Pix CobV do Banco Central. Você pode enviar o `invoice` e `invoiceItems` aqui também, se desejar nota fiscal.

```json
{
  "paymentMethod": "PIX",
  "description": "Mensalidade referente a Agosto/2026",
  "amount": {
    "original": 150.00,
    "interest": { "type": "PERCENTAGE", "value": 1.00 }, // Juros ao mês por atraso
    "fine": { "type": "PERCENTAGE", "value": 2.00 },     // Multa fixa por atraso
    "discount": { "type": "FIXED", "value": 5.00 }       // Desconto de R$ 5,00
  },
  "calendar": {
    "dueDate": "2026-08-10",       // Data de vencimento
    "validityAfterDue": 30         // Dias de validade do QRCode após vencimento
  },
  "payer": {
    "name": "João da Silva",
    "document": "12345678900",
    "address": {
      "street": "Rua X 10",
      "neighborhood": "Centro",
      "city": "São Paulo",
      "state": "SP",
      "zipCode": "01000000"
    }
  }
}
```

**Pré-cadastro de Produtos (Opcional):** `POST /v1/products`
*(Se o Lojista quiser usar a Opção 1 no Pix)*
```json
{
  "name": "Licença de Software",
  "type": "SERVICE",
  "ncm": "85235110",
  "cfop": "5101",
  "serviceCode": "01.01",
  "unitPrice": 150.00
}
```

**Resposta:**
```json
{
  "txId": "UUID da transação",
  "qrCodeImage": "Base64 do QRCode",
  "qrCodeText": "Pix copia e cola"
}
```

**Consultar Status de uma Cobrança:** `GET /v1/charges/{txId}`
**Listar Todas as Cobranças:** `GET /v1/charges`
*(Ambos retornam o status atual da cobrança: `PENDING`, `PAID`, `CANCELLED`)*

## 3. Webhooks (Notificação de Pagamento)

A Xingubit Pay enviará um `POST` para a URL configurada pelo Lojista no dashboard quando o Pix for pago.

**Payload recebido no seu sistema (POST):**
```json
{
  "status": "PAID",
  "txId": "UUID",
  "externalContractId": "SEU-ID-123",
  "amount": 150.00,
  "paidAt": "2026-06-30T16:30:00Z"
}
```
**Atenção:** O seu sistema DEVE retornar HTTP `200 OK`.

**Configurar a URL de Webhook via API:** `PUT /v1/merchants/me/webhook`
**Header:** `Authorization: Bearer {token}`
**Body:**
```json
{
  "webhookUrl": "https://seu-sistema.com.br/api/webhook/pix"
}
```
*(Para consultar a atual, use `GET /v1/merchants/me/webhook`)*

## 4. Cashout (Saque via Pix)

Envie Pix usando o saldo da sua conta. O saldo é debitado na hora.

**Endpoint:** `POST /v1/cashouts`
**Header:** `Authorization: Bearer {token}`
**Content-Type:** `application/json`

**Body:**
```json
{
  "pixKey": "chave-pix-do-destino",
  "amount": 500.00
}
```

## 5. Saldo

**Endpoint:** `GET /v1/merchants/me/balance`
**Header:** `Authorization: Bearer {token}`

**Resposta:**
```json
{
  "available_balance": 14520.00,
  "pending_balance": 0.00
}
```

## 6. Emissão de Notas Fiscais Eletrônicas (NFS-e, NF-e, NFCom)

Se configurado previamente no painel, a plataforma Xingubit Pay emite as notas automaticamente quando o Pix é pago, mas você também pode gerá-las de forma **avulsa** via API, sem vínculo com uma cobrança Pix.

A API possui um motor genérico que suporta múltiplas notas. O endpoint base é:
**Endpoint:** `POST /v1/invoices/{docType}` (Substitua `{docType}` por `nfe`, `nfse` ou `nfcom`)
**Header:** `Authorization: Bearer {token}`

Esses endpoints funcionam como proxy direto para os formatos padrão nacional da ACBr.

### Exemplo 1: Emitir NF-e Avulsa (`POST /v1/invoices/nfe`)
```json
{
  "ambiente": "homologacao",
  "emitente": {
    "cpf_cnpj": "12345678000199",
    "razao_social": "Minha Empresa Ltda"
  },
  "destinatario": {
    "cpf_cnpj": "98765432100",
    "razao_social": "Cliente Final",
    "endereco": {
      "logradouro": "Rua das Flores",
      "numero": "123",
      "bairro": "Centro",
      "uf": "SP",
      "cep": "01000000"
    }
  },
  "itens": [
    {
      "numero_item": 1,
      "produto": {
        "descricao": "Licença de Software",
        "ncm": "85235110",
        "cfop": "5101",
        "quantidade": 1,
        "valor_unitario": "150.00",
        "valor_total": "150.00"
      }
    }
  ]
}
```

### Exemplo 2: Emitir NFCom Avulsa (`POST /v1/invoices/nfcom`)
A NFCom (Fatura de Comunicação) exige dados específicos de assinante e modelo.
```json
{
  "ambiente": "homologacao",
  "emitente": {
    "cpf_cnpj": "12345678000199",
    "razao_social": "Minha Telecom Ltda",
    "ie": "123456789"
  },
  "assinante": {
    "cpf_cnpj": "98765432100",
    "nome_razao_social": "Cliente Final",
    "tipo_assinante": "1",
    "endereco": {
      "logradouro": "Rua das Flores",
      "numero": "123",
      "bairro": "Centro",
      "uf": "SP",
      "cep": "01000000"
    }
  },
  "itens": [
    {
      "numero_item": 1,
      "servico": {
        "descricao": "Plano de Internet Fibra 500MB",
        "cfop": "5307",
        "codigo_tributacao": "01.01",
        "quantidade": 1,
        "valor_unitario": "99.90",
        "valor_total": "99.90"
      }
    }
  ]
}
```

### Demais Operações Fiscais

- **Consultar PDF Avulso:** `GET /v1/invoices/{docType}/{id}/pdf`
- **Consultar XML Avulso:** `GET /v1/invoices/{docType}/{id}/xml`
- **Cancelar Nota:** `POST /v1/invoices/{docType}/{id}/cancelamento`
- **Consultar PDF vinculado à cobrança Pix:** `GET /v1/charges/{txId}/invoice/pdf`

- **Configurar NFS-e (Dados da sua empresa):** `PUT /v1/empresas/{cnpj}/config/nfse`
**Body:**
```json
{
  "ambiente": "homologacao",
  "lote": 1,
  "serie": "1",
  "numero": 1
}
```

- **Consultar PDF (DANFE) Avulso:** `GET /v1/nfe/{id}/pdf`
- **Consultar PDF vinculado à cobrança Pix:** `GET /v1/charges/{txId}/invoice/pdf`
**Header:** `Authorization: Bearer {token}`
**Content-Type:** `application/json`

**Body (JSON - Exemplo Simplificado):**
```json
{
  "natureza_operacao": "VENDA DE MERCADORIA",
  "tipo_documento": 1,
  "finalidade_emissao": 1,
  "destinatario": {
    "cpf_cnpj": "12345678909",
    "nome": "Cliente Final Exemplo",
    "email": "cliente@email.com",
    "endereco": {
      "logradouro": "Rua Exemplo",
      "numero": "123",
      "bairro": "Centro",
      "codigo_municipio": "3550308",
      "cidade": "São Paulo",
      "uf": "SP",
      "cep": "01000000"
    }
  },
  "itens": [
    {
      "numero_item": 1,
      "codigo_produto": "PROD01",
      "descricao": "Produto de Teste",
      "ncm": "99999999",
      "cfop": "5102",
      "unidade_comercial": "UN",
      "quantidade_comercial": 1.0,
      "valor_unitario_comercial": 150.00,
      "impostos": {
        "icms": { "situacao_tributaria": "102" },
        "pis": { "situacao_tributaria": "08" },
        "cofins": { "situacao_tributaria": "08" }
      }
    }
  ],
  "pagamento": {
    "formas_pagamento": [
      {
        "meio_pagamento": "17", 
        "valor": 150.00 
      }
    ]
  }
}
```

## Erros Comuns

- `400 Bad Request`: Dados mal formatados.
- `401 Unauthorized`: Token inválido, expirado ou não enviado.
- `403 Forbidden`: Sem permissão de acesso.
- `404 Not Found`: Recurso (`txId`) não localizado.