Clés PIX

Liste les clés PIX enregistrées sur le compte associé à l'API Key.

Endpoint

GET /api/external/pix/keys

Headers

Header	Type	Obligatoire	Description
Authorization	String	Oui	ApiKey {client_id}:{client_secret}
X-Key-Case	String	Non	Définissez à camelCase pour recevoir les champs de la réponse en camelCase (par défaut snake_case)

Exemple

curl -X GET https://api.owem.com.br/api/external/pix/keys \
  -H "Authorization: ApiKey $CLIENT_ID:$CLIENT_SECRET"

Réponse de succès (200)

{
  "worked": true,
  "keys": [
    {
      "key": "12345678901",
      "key_type": "cpf",
      "status": "active",
      "created_at": "2026-02-05T12:00:00Z"
    },
    {
      "key": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
      "key_type": "evp",
      "status": "active",
      "created_at": "2026-02-10T14:30:00Z"
    },
    {
      "key": "contato@empresa.com.br",
      "key_type": "email",
      "status": "active",
      "created_at": "2026-02-15T09:00:00Z"
    }
  ]
}

Champ	Type	Description
worked	Boolean	true indique le succès de l'opération
keys	Array	Liste des clés PIX du compte, triée par inserted_at ASC (de la plus ancienne à la plus récente). Note : quand la facturation PIX IN (POST /pix/cash-in) est générée sans le paramètre pix_key, le backend utilise en interne la clé active la plus récente (DESC) du compte -- ordre différent de cet endpoint.
keys[].key	String	Valeur de la clé PIX
keys[].key_type	String	Type de la clé en minuscules (voir tableau ci-dessous)
keys[].status	String	Status actuel de la clé (voir tableau ci-dessous)
keys[].created_at	String	Date d'enregistrement (ISO 8601 en UTC)

Sans pagination

Cet endpoint retourne toutes les clés du compte dans une seule réponse (les comptes PF admettent jusqu'à 5 clés, PJ jusqu'à 20). Il n'y a pas de paramètres limit, offset, page ou per_page -- l'envoi de ces paramètres est silencieusement ignoré.

Types de clé

Type	Format	Exemple
cpf	11 chiffres	12345678901
cnpj	14 chiffres	12345678000190
email	Email valide	contato@empresa.com.br
phone	DDD + numéro (11 chiffres)	11999998888
evp	UUID v4 (clé aléatoire)	a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d

Status de la clé

Le schéma de base accepte seulement deux valeurs pour status :

Status	Description
active	Clé active et opérationnelle -- peut recevoir du PIX et être utilisée comme pix_key dans POST /pix/cash-in
pending	Enregistrement en cours dans le DICT (flux de création de clé initié mais pas encore confirmé par le BACEN)

Clés affichées

L'endpoint retourne toutes les clés liées au compte (indépendamment du status). Filtrez par le champ status === "active" côté client si vous ne voulez que les clés opérationnelles.

Portabilité et revendications

La portabilité n'est pas un status de la clé. La portabilité (amener une clé d'une autre institution) et la revendication (contester la possession) sont des workflows séparés, disponibles uniquement dans le portail du merchant ou via le panneau administratif -- non exposés par l'API externe.

Réponse d'erreur (401)

{
  "error": {
    "status": 401,
    "message": "Missing API key credentials. Use Authorization: ApiKey <client_id>:<client_secret>"
  }
}

API externe en lecture seule

Cet endpoint liste uniquement les clés existantes. L'enregistrement, la portabilité, la revendication et la suppression de clés PIX se font exclusivement via le portail du merchant (merchant.owem.com.br) ou le panneau administratif -- il n'y a pas d'endpoints externes pour ces opérations.

Information sur les limites (gérées par le backend, non exposées par l'API) : les comptes PF admettent jusqu'à 5 clés, les comptes PJ jusqu'à 20, avec 1 clé CPF/CNPJ par compte.