Listar conductores asociados y su estado

Parámetros, estructura de datos y respuestas del contrato versionado.

GET/agregados

listarAgregadosBase de Pruebas: https://api.fleetpay.site/v1

Las descripciones técnicas se traducen del contrato versionado. Se conservan los identificadores y el JSON originales; se omiten los ejemplos de datos.

Lista a quienes trabajan para su empresa en FleetPay y responde la pregunta clave: ¿este conductor o transportista agregado ya puede recibir fondos?

Es la otra parte de la invitación. POST /convites/transportadoras inicia la conversación; este endpoint informa de su avance sin necesidad de consultar al soporte.

Quién aparece en la lista depende del vínculo, no de quién creó el registro:

`tipo`	Quién es
`motorista`	conductor agregado de su empresa (o de una sucursal de su grupo)
`transportadora`	transportista que contrata o a quien invitó

Una transportista invitada aparece aquí antes de completar el registro, con cadastro: "convidado": precisamente durante el período en el que necesita seguir su avance. Cuando lo completa, la misma fila pasa a cadastro: "cadastrado" y muestra la cuenta.

El campo decisivo es conta.habilitado_a_receber. Ya combina el estado de la cuenta, la biometría y el bloqueo; situacao, biometria y pendencia permiten explicar a su operador qué falta, no recalcular la regla.

Esta consulta no devuelve un número de cuenta ni una clave Pix. Indica si el conductor o transportista agregado puede recibir fondos, no por dónde: FleetPay sigue gestionando el pago.

Autenticación

[
  {
    "oauth2": []
  },
  {
    "chaveApi": []
  }
]

La disponibilidad depende del entorno, los permisos habilitados y el proveedor. Esta referencia no ejecuta solicitudes ni recibe credenciales.

Parámetros

tipoquery · stringOpcional

Filtra por tipo de colaborador. Si se omite, devuelve ambos tipos.

Restricciones

{
  "type": "string",
  "enum": [
    "motorista",
    "transportadora"
  ]
}

paginaquery · integerOpcional

Restricciones

{
  "type": "integer",
  "minimum": 1,
  "default": 1
}

por_paginaquery · integerOpcional

Máximo de 200 por página.

Restricciones

{
  "type": "integer",
  "minimum": 1,
  "maximum": 200,
  "default": 50
}

Respuestas

200 Respuesta HTTP

Lista de colaboradores de tu empresa

`application/json`

RespostaAgregados ↗

dataarrayObligatorio

Agregado ↗

metaobjectObligatorio

PaginacaoAgregados ↗

ambienteobjectObligatorio

Ambiente ↗

400 Respuesta HTTP

Solicitud inválida

`application/json`

Erro ↗

errorobjectOpcional

401 Respuesta HTTP

Sin autenticación (autenticacao): credencial ausente, inválida o vencida, incluida una clave API utilizada en el entorno incorrecto. La clave de homologación no es válida en producción, ni la de producción en homologación; el mensaje de error indica el entorno esperado.

`application/json`

Erro ↗

errorobjectOpcional

403 Respuesta HTTP

Ámbito no habilitado para esta credencial

`application/json`

Erro ↗

errorobjectOpcional

429 Respuesta HTTP

Límite de solicitudes excedido (limite_requisicoes). Espera el intervalo indicado en el encabezado Retry-After antes de reintentar. Puede provenir del proveedor o del límite antiabuso de FleetPay, calculado por empresa autenticada y grupo de rutas, con una ventana corta para ráfagas y otra larga para tráfico automatizado lento. Los límites son amplios deliberadamente: las integraciones reales, incluidos lotes grandes procesados de una vez, deberían quedar muy por debajo. Si tu integración alcanza un límite, contacta con FleetPay.

`application/json`

Erro ↗

errorobjectOpcional

500 Respuesta HTTP

Error interno (erro_interno)

`application/json`

Erro ↗

errorobjectOpcional

Definición Completa de la Operación

{
  "tags": [
    "Agregados"
  ],
  "summary": "Listar os seus agregados e a situação de cada um",
  "operationId": "listarAgregados",
  "description": "Lista quem trabalha para a sua empresa na FleetPay e responde a pergunta que importa:\n**este agregado já pode receber?**\n\nÉ o outro lado do convite. `POST /convites/transportadoras` inicia a conversa; este\nendpoint conta onde ela chegou, sem você precisar perguntar ao suporte.\n\n**Quem entra na lista** — o vínculo, não o cadastro que você fez:\n\n| `tipo` | Quem é |\n|---|---|\n| `motorista` | motorista agregado da sua empresa (ou de uma filial do seu grupo) |\n| `transportadora` | transportadora que você contrata, **ou** que você convidou |\n\nUma transportadora que você convidou aparece aqui **antes** de concluir o cadastro, com\n`cadastro: \"convidado\"` — é exatamente o intervalo em que você quer saber se ela andou.\nQuando ela conclui, a mesma linha passa a `cadastro: \"cadastrado\"` e a mostrar a conta.\n\n**O campo que decide é `conta.habilitado_a_receber`.** Ele já combina situação da conta,\nbiometria e bloqueio; `situacao`, `biometria` e `pendencia` existem para você explicar ao\nseu operador o que falta, não para você recalcular a regra.\n\n> Esta consulta **não** devolve número de conta nem chave PIX. Ela responde *se* o\n> agregado pode receber, não por onde — o pagamento continua sendo conduzido pela\n> FleetPay.\n",
  "parameters": [
    {
      "name": "tipo",
      "in": "query",
      "required": false,
      "schema": {
        "type": "string",
        "enum": [
          "motorista",
          "transportadora"
        ]
      },
      "description": "Filtra por natureza do agregado. Ausente, traz os dois."
    },
    {
      "name": "pagina",
      "in": "query",
      "required": false,
      "schema": {
        "type": "integer",
        "minimum": 1,
        "default": 1
      }
    },
    {
      "name": "por_pagina",
      "in": "query",
      "required": false,
      "schema": {
        "type": "integer",
        "minimum": 1,
        "maximum": 200,
        "default": 50
      },
      "description": "Máximo de 200 por página."
    }
  ],
  "responses": {
    "200": {
      "description": "Lista dos agregados da sua empresa",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/RespostaAgregados"
          }
        }
      }
    },
    "400": {
      "$ref": "#/components/responses/Erro400"
    },
    "401": {
      "$ref": "#/components/responses/Erro401"
    },
    "403": {
      "$ref": "#/components/responses/Erro403"
    },
    "429": {
      "$ref": "#/components/responses/Erro429"
    },
    "500": {
      "$ref": "#/components/responses/Erro500"
    }
  },
  "method": "GET",
  "path": "/agregados"
}