Contar colaboradores

GET /api/v1/valepix/employees/count

Retorna a quantidade total de colaboradores associados à empresa autenticada pelo API token. Útil para dashboards, relatórios e verificações rápidas de quantos colaboradores estão atualmente cadastrados na integração.

Autenticação

Envie um API token ativo no header Authorization.

Authorization: Bearer <VALEPIX_API_TOKEN>
Accept: application/json

Path params

Esta rota não possui path params.

Query params

Esta rota não possui query params documentados. A empresa de referência é resolvida pelo API token enviado.

Exemplo curl

curl --request GET \
  --header "Authorization: Bearer $VALEPIX_API_TOKEN" \
  --header "Accept: application/json" \
  --url "https://routes.valepix.com.br/api/v1/valepix/employees/count"

Response

HTTP 200 OK.

{
  "success": "success",
  "data": {
    "total": 42
  }
}

Campo	Tipo	Descrição
total	number	Quantidade total de colaboradores associados à empresa autenticada pelo token

Como usar o resultado

• Exibir totais em painéis internos da integração.
• Validar se o cadastro em lote refletiu na quantidade esperada após o commit.
• Monitorar crescimento do quadro associado ao benefício.

Erros comuns

HTTP	Quando acontece	Ação recomendada
401	Token ausente, inválido, expirado ou revogado	Conferir token
403	Token sem acesso ao recurso solicitado	Confirmar token com a ValePix
429	Limite de requisições excedido	Aplicar backoff e respeitar o rate limit
500	Erro interno temporário	Tentar novamente com backoff

Fluxo simplificado

sequenceDiagram
    participant Cliente as Cliente externo
    participant Gateway as API Gateway (vp-service-routes)
    participant Core as vp-service-core

    Cliente->>Gateway: GET /api/v1/valepix/employees/count<br/>Authorization: Bearer <api token>
    Gateway->>Gateway: ApiTokenAuth + SanitizeInput + RateLimit
    Gateway->>Core: CountEmployeesByBusiness (gRPC)
    Core->>Core: Resolve business pelo token<br/>e conta colaboradores
    Core-->>Gateway: { total }
    Gateway-->>Cliente: 200 { success, data: { total } }

Cenários de erro

• Token revogado ou expirado: a chamada retorna 401. Solicite um novo token à ValePix.
• Token não autorizado para a operação: retorna 403. Confirme com a ValePix se o token possui acesso ao recurso.
• Excesso de requisições no curto prazo: retorna 429. Aplique espera exponencial.

Arquivos de referência

• vp-service-routes/internal/api/routes.go — registro da rota GET /valepix/employees/count no grupo externo (registerExternalRoutes).
• vp-service-routes/internal/api/handlers/core/employees.go — HandleCountEmployeesByBusiness.
• vp-service-routes/internal/core/strategy/core/employees.go — handleCountEmployeesByBusiness (strategy gRPC).
• vp-service-routes/internal/adapter/grpc/core/employees.go — CountEmployeesByBusiness (cliente gRPC).

FAQ

Posso filtrar por situação? Atualmente esta rota retorna apenas o total agregado da empresa autenticada pelo token. Para contagens segmentadas por situação, utilize Listar colaboradores com o filtro situation e leia o campo meta.total da resposta.

O total inclui colaboradores desligados ou bloqueados? A rota retorna o total de colaboradores associados ao business autenticado, conforme registrado em vp-service-core. Para validar quais situações compõem a contagem em sua integração específica, valide consultando Listar colaboradores com diferentes filtros de situation.

Posso passar um business_id na query? Não. A empresa é resolvida pelo API token. O token sempre opera no contexto de uma única empresa autorizada.