Saltar al contenido principal

Ficha técnica

Alcances necesarios​

El token para consumir la API de Nómina debe ser generado utilizando el Authorization Code.

El alcance openid es obligatorio. Permite consultar el perfil del usuario BTG con acceso a la cuenta.

Es necesario incluir los siguientes alcances:

AlcanceDescripción
brn:btg:empresas:banking:payrollPermite el manejo completo de la API de Nómina

Nómina — Visión General de la API

La API de Nómina de BTG Empresas permite que su empresa gestione pagos masivos y el registro de colaboradores de forma centralizada, segura y trazable. Esta documentación presenta los principales flujos disponibles y cómo utilizarlos en el día a día de su operación.

Flujo de Pagos​

El flujo de pagos se organiza en torno al concepto de lote: un agrupamiento de pagos enviados juntos para procesamiento. Esto permite que su equipo financiero tenga control granular sobre cada remesa, con trazabilidad completa de estados e historial de transacciones.

Crear Lote de Pago​

El punto de entrada del flujo es el envío de un lote. En esta etapa, se agrupan los pagos que deben procesarse en una misma remesa. La API admite una amplia variedad de modalidades, como salario, anticipo, vacaciones, décimo tercer salario, liquidación, PLR, honorarios, beca de pasantía, beneficio, reembolso, comisión, dividendos y otras.

Al enviar el lote, se define para cada línea el colaborador destinatario, el valor neto, los datos bancarios de crédito y la fecha programada para la ejecución. El envío se procesa de forma asíncrona: la API retorna inmediatamente con el identificador del lote y el procesamiento ocurre en segundo plano.

Solicitud — POST /{companyId}/banking/payroll/payments

{
  "description": "Folha de Pagamento - Junho 2026",
  "scheduledDate": "2026-06-30T00:00:00Z",
  "paymentType": 2,
  "companies": [
    {
      "taxId": "12345678000190",
      "debitParty": {
        "branchCode": "0001",
        "number": "123456-7"
      },
      "items": [
        {
          "taxId": "12345678901",
          "bankCode": "208",
          "branchCode": "0001",
          "accountNumber": "987654-3",
          "netAmount": 4500.00,
          "reference": "João Silva - Salário Jun/2026"
        },
        {
          "taxId": "98765432100",
          "bankCode": "208",
          "branchCode": "0001",
          "accountNumber": "112233-4",
          "netAmount": 7200.00,
          "reference": "Maria Souza - Salário Jun/2026"
        }
      ]
    }
  ]
}

El header X-Idempotency-Key (UUID v4) es obligatorio para evitar el procesamiento duplicado en caso de reintento.

Respuesta — 202 Accepted

{
  "requestId": "a3f1b2c4-9d8e-4f5a-b6c7-d8e9f0a1b2c3",
  "paymentId": 78432,
  "status": "submitted",
  "submittedAt": "2026-06-17T14:23:11Z",
  "totalEmployees": 2,
  "totalAmount": 11700.00,
  "scheduledDate": "2026-06-30T00:00:00Z"
}

Conserve el requestId y el paymentId retornados: se utilizan en las operaciones de consulta y cancelación del lote.

Listado de Pagos​

Todos los lotes enviados quedan disponibles para consulta. El listado permite que su equipo realice un seguimiento del estado de cada remesa — identificando lotes enviados, en aprobación, liquidados, con falla o cancelados — y aplique filtros por período, estado, referencia u otros criterios relevantes para su contexto.

Atención: el listado aplica un filtro implícito por ventana de tiempo. Los pagos fuera de la ventana predeterminada pueden no aparecer incluso después de la liquidación. Utilice los filtros startDate y endDate para ampliar el período de búsqueda cuando sea necesario.

Respuesta — GET /{companyId}/banking/payroll/payments?startDate=2026-06-01&endDate=2026-06-30

{
  "links": {
    "next": { "href": "/btg-company/banking/payroll/payments?cursor=eyJwYWdlIjoyfQ==" },
    "prev": null
  },
  "data": [
    {
      "requestId": "a3f1b2c4-9d8e-4f5a-b6c7-d8e9f0a1b2c3",
      "paymentId": 78432,
      "reference": "Folha de Pagamento - Junho 2026",
      "scheduledDate": "2026-06-30",
      "debitDate": "2026-06-30",
      "status": "settled",
      "paymentType": "PAG_SALARIO",
      "validatedAmount": 11700.00,
      "originalAmount": 11700.00,
      "paidAmount": 11700.00,
      "errorTransferCount": 0,
      "company": {
        "name": "Empresa Exemplo Ltda",
        "taxId": "12345678000190",
        "account": { "branch": "0001", "number": "123456-7" }
      },
      "links": {
        "self": { "href": "/btg-company/banking/payroll/payments/78432" }
      }
    }
  ]
}

Detalles del Lote de Pago​

Para cada lote, es posible acceder a una vista detallada con todas las líneas de pago que lo componen. Esta consulta muestra el estado individual de cada transacción, los valores involucrados, contadores de liquidaciones y fallas, y cualquier información de retorno del procesamiento bancario — como confirmaciones o errores por línea.

Los estados finales de un lote son settled (liquidado), failed (fallido) y cancelled (cancelado). Use esta vista para auditar remesas específicas, identificar divergencias y obtener la vista consolidada de la operación.

Respuesta — GET /{companyId}/banking/payroll/payments/78432

{
  "paymentId": 78432,
  "description": "Folha de Pagamento - Junho 2026",
  "status": "settled",
  "debitParty": { "branchCode": "0001", "number": "123456-7" },
  "submittedAt": "2026-06-17T14:23:11Z",
  "approvedAt": "2026-06-17T15:00:00Z",
  "settledAt": "2026-06-30T10:15:33Z",
  "cancelledAt": null,
  "scheduledDate": "2026-06-30T00:00:00Z",
  "totalEmployees": 2,
  "totalAmount": 11700.00,
  "settledCount": 2,
  "failedCount": 0,
  "items": [
    {
      "employeeId": "emp-001",
      "name": "João Silva",
      "taxId": "12345678901",
      "line": 1,
      "paymentType": "PAG_SALARIO",
      "netAmount": 4500.00,
      "status": "settled",
      "transactionStatus": "LIQUIDADO",
      "settledAt": "2026-06-30T10:15:33Z",
      "failureReason": null
    },
    {
      "employeeId": "emp-002",
      "name": "Maria Souza",
      "taxId": "98765432100",
      "line": 2,
      "paymentType": "PAG_SALARIO",
      "netAmount": 7200.00,
      "status": "settled",
      "transactionStatus": "LIQUIDADO",
      "settledAt": "2026-06-30T10:15:33Z",
      "failureReason": null
    }
  ],
  "links": {
    "self": { "href": "/btg-company/banking/payroll/payments/78432" },
    "cancel": null
  }
}

Cancelar Lote de Pago​

Es posible cancelar un lote que ya fue enviado, siempre que aún se encuentre en los estados submitted (enviado) o pending_approval (en espera de aprobación). La cancelación interrumpe el procesamiento del lote de forma íntegra.

Esta operación es irreversible: una vez cancelado, el lote no puede ser reactivado. Si necesita reprocesar los pagos, deberá crearse un nuevo lote.

Solicitud — POST /{companyId}/banking/payroll/payments/{requestId}/cancel

{
  "reason": "Erro nos valores informados. Novo lote será submetido em seguida."
}

Respuesta — 200 OK

La respuesta confirma la cancelación sin cuerpo adicional. Para verificar el estado actualizado del lote, consulte los detalles a través de GET /payments/{paymentId}.

Flujo de Colaboradores​

La gestión de colaboradores es lo que hace viable el flujo de pagos: cada destinatario de un lote debe estar registrado, con cuenta bancaria válida y estado activo en la plataforma. La API ofrece endpoints para cubrir todo el ciclo de vida de un colaborador — desde el onboarding hasta la desvinculación y reactivación.

Solicitud de Apertura de Cuenta​

Para que un colaborador pueda recibir pagos a través de nómina, es necesario registrarlo y solicitar la apertura de una cuenta digital BTG Empresas a su nombre. La solicitud se realiza con los datos de registro del colaborador — como CPF, nombre completo, fecha de admisión, salario bruto mensual, correo electrónico, teléfono, dirección y documento de identidad con el respectivo emisor — y desencadena el proceso de análisis y creación de la cuenta.

El envío es asíncrono: la API retorna 202 Accepted inmediatamente, y el procesamiento ocurre en segundo plano. El resultado puede seguirse consultando los detalles del colaborador o el estado de su cuenta bancaria.

El campo issuingAuthority acepta únicamente los códigos retornados por el endpoint GET /{companyId}/banking/payroll/onboarding/issuers. Los valores fuera de esta lista son rechazados con 400 Bad Request.

Solicitud — POST /{companyId}/banking/payroll/onboarding/employees

[
  {
    "companyTaxId": "12345678000190",
    "name": "Carlos Eduardo Mendes",
    "taxId": "34567890123",
    "email": "carlos.mendes@empresa.com.br",
    "phone": "11987654321",
    "admissionDate": "2026-06-01",
    "grossMonthlySalary": 5800.00,
    "accountType": "CHECKING",
    "idNumber": "12.345.678-9",
    "issuingAuthority": "SSP-SP",
    "address": {
      "street": "Rua das Flores",
      "number": "42",
      "neighborhood": "Vila Madalena",
      "zipCode": "05443000"
    },
    "isUnderage": false
  }
]

Respuesta — 202 Accepted

{
  "status": "accepted"
}

Listado de Colaboradores​

El listado presenta todos los colaboradores vinculados a su empresa, con sus respectivos estados. A partir de esta vista, es posible identificar colaboradores con cuenta activa (active), onboarding en curso (pending), cuenta suspendida (suspended) y colaboradores desvinculados (inactive).

El listado admite filtros por estado, nombre, CPF, tipo de cuenta, portabilidad y tipo de contrato, además de paginación por cursor, siendo adecuado tanto para uso en interfaces administrativas como para integraciones automatizadas con sistemas de RR.HH.

Respuesta — GET /{companyId}/banking/payroll/employees?status=active&pageSize=2

{
  "data": [
    {
      "name": "João Silva",
      "taxId": "12345678901",
      "status": "active",
      "isActive": true,
      "onboardingCompleted": "true",
      "isSuspended": false,
      "admissionDate": "2024-03-01T00:00:00Z",
      "terminationDate": null,
      "company": { "name": "Empresa Exemplo Ltda", "taxId": "12345678000190" },
      "accounts": [
        { "type": "CHECKING", "status": "active", "bankCode": "208", "branch": "0001", "number": "987654-3" }
      ],
      "links": { "self": { "href": "/btg-company/banking/payroll/employees/12345678901" } }
    },
    {
      "name": "Maria Souza",
      "taxId": "98765432100",
      "status": "active",
      "isActive": true,
      "onboardingCompleted": "true",
      "isSuspended": false,
      "admissionDate": "2023-07-15T00:00:00Z",
      "terminationDate": null,
      "company": { "name": "Empresa Exemplo Ltda", "taxId": "12345678000190" },
      "accounts": [
        { "type": "CHECKING", "status": "active", "bankCode": "208", "branch": "0001", "number": "112233-4" }
      ],
      "links": { "self": { "href": "/btg-company/banking/payroll/employees/98765432100" } }
    }
  ],
  "links": {
    "next": { "href": "/btg-company/banking/payroll/employees?cursor=eyJwYWdlIjoyfQ==&status=active" },
    "previous": null
  }
}

Seguimiento de la Apertura de Cuenta​

Por ser un proceso asíncrono, la apertura de cuenta puede seguirse de dos formas: consultando el estado del colaborador en el listado general (donde aparecerá como pending mientras el onboarding esté en curso) o consultando específicamente los datos de la cuenta bancaria del colaborador, que retorna el estado actual del onboarding, la fecha de conclusión y posibles errores.

Se recomienda implementar un mecanismo de polling en estas consultas para monitorear la evolución del estado sin necesidad de verificaciones manuales recurrentes.

Respuesta — GET /{companyId}/banking/payroll/employees/{employeeTaxId}/account

Cuenta aún en procesamiento:

{
  "employeeId": "emp-003",
  "accountType": "CHECKING",
  "status": "pending",
  "onboardingFinalizado": false,
  "onboardingFinishedAt": null,
  "errors": null,
  "bank": null,
  "agency": null,
  "number": null,
  "links": {
    "self": { "href": "/btg-company/banking/payroll/employees/34567890123/account" },
    "employee": { "href": "/btg-company/banking/payroll/employees/34567890123" }
  }
}

Cuenta activada con éxito:

{
  "employeeId": "emp-003",
  "accountType": "CHECKING",
  "status": "active",
  "onboardingFinalizado": true,
  "onboardingFinishedAt": "2026-06-18T09:42:00Z",
  "errors": null,
  "bank": "208",
  "agency": "0001",
  "number": "445566-7",
  "links": {
    "self": { "href": "/btg-company/banking/payroll/employees/34567890123/account" },
    "employee": { "href": "/btg-company/banking/payroll/employees/34567890123" }
  }
}

Detalles del Colaborador​

La consulta de detalles retorna el perfil completo de un colaborador registrado: sus datos personales, estado actual, tipo de contrato, información de portabilidad, fechas de admisión y desvinculación, estado de suspensión y la información de cuenta bancaria vinculada.

Use esta consulta para verificar la elegibilidad de un colaborador para recibir pagos antes de incluirlo en un lote, o para soporte y auditoría de casos específicos.

Respuesta — GET /{companyId}/banking/payroll/employees/{employeeTaxId}

{
  "employeeId": "emp-001",
  "name": "João Silva",
  "taxId": "12345678901",
  "status": "active",
  "contractType": "CLT",
  "portability": false,
  "admissionDate": "2024-03-01T00:00:00Z",
  "terminationDate": null,
  "suspended": false,
  "suspensionEndDate": null,
  "accounts": [
    { "type": "CHECKING", "status": "active", "agency": "0001", "number": "987654-3" }
  ],
  "company": { "cnpj": "12345678000190", "name": "Empresa Exemplo Ltda" },
  "links": {
    "self": { "href": "/btg-company/banking/payroll/employees/12345678901" },
    "deactivate": { "href": "/btg-company/banking/payroll/employees/12345678901/deactivate", "method": "POST" },
    "reactivate": null
  }
}

Desactivar y Activar Colaborador​

Al desvincular un colaborador, es posible registrar el fin del vínculo laboral en la plataforma. Esta operación está disponible para colaboradores con estado active y los mueve al estado inactive, impidiendo que sean incluidos en nuevos lotes de pago. La desvinculación acepta fecha de rescisión y motivo.

Solicitud — POST /{companyId}/banking/payroll/employees/{employeeTaxId}/deactivate

{
  "terminationDate": "2026-06-30",
  "reason": "Demissão sem justa causa"
}

Respuesta — 200 OK

{
  "employeeId": "emp-001",
  "status": "inactive",
  "terminationDate": "2026-06-30",
  "requestedAt": "2026-06-17T16:05:22Z",
  "links": {
    "self": { "href": "/btg-company/banking/payroll/employees/12345678901" },
    "reactivate": { "href": "/btg-company/banking/payroll/employees/12345678901/reactivate", "method": "POST" }
  }
}

La reactivación también está disponible: si el colaborador regresa a la empresa, puede ser reactivado — siempre que se encuentre en el estado inactive — volviendo al estado active y haciéndose elegible nuevamente para recibir pagos a través de nómina.

Solicitud — POST /{companyId}/banking/payroll/employees/{employeeTaxId}/reactivate

Sin cuerpo de solicitud.

Respuesta — 200 OK

{
  "employeeId": "emp-001",
  "status": "active",
  "reactivatedAt": "2026-08-01T09:10:00Z",
  "links": {
    "self": { "href": "/btg-company/banking/payroll/employees/12345678901" },
    "deactivate": { "href": "/btg-company/banking/payroll/employees/12345678901/deactivate", "method": "POST" }
  }
}