Skip to main content
A partner can call BC Correios with its own credential. In BC Correios, you confine that credential to some mails. This page shows how to choose that scope, what it reaches, and what the partner receives when it goes outside it. Every BC Correios partner needs a scope: at least one mail.

Step by step

1

Choose what the partner works with

One installation of BC Correios serves one institution, so the mail is the only item you can confine a partner to. The API field is the field of a scope entry; the Console shows the name in the first column.Each value is the ID that BC Correios returns for the mail.The scope catalog lists the BC Correios restriction. Read it with Retrieve a product’s scope catalog for plugin-bc-correios.Some rules apply to every scope:
  • A request that does not name a mail is refused. For example, a partner cannot list or count the mails of your institution: it reads only the mails whose IDs you give it.
  • A query that lists several mails is refused when any one of them is outside the scope.
  • Routes that act on the whole installation are refused to every partner: settings, the dashboard, the audit export, the runtime configuration, and the streaming manifest.
2

Give the partner its permissions and scope

Create the partner, or change it, in the Console or with the Identity API. The product slug is plugin-bc-correios.
  • Add at least one scope entry for BC Correios. Without one, Access Manager refuses the partner with 400 and IDE-1060.
  • Check the resources and actions. The most you can give is what the plugin-bc-correios-editor-role role holds in your tenant.
Access Manager checks each write you give against the scope. A write that acts on the whole installation is never given to a partner, and is refused with 400 and IDE-1056. The Console marks the line Outside the scope. In BC Correios, these writes are creating and changing settings, testing the BC Correio and AI connections, and changing the runtime configuration.The writes a partner can receive are mails with post (a reply, a new AI analysis) and mails with put (archive, restore).
3

Create its BC Correios application

Create the partner’s application with the product plugin-bc-correios. See Create the partner’s applications in the API guide, or in the Console. Send the client ID and the client secret to the partner through a secure channel.
4

Tell the partner how to name its mails

On most routes the mail is already in the path. On the others, the partner names it in the query or the body that BC Correios already has. Every route below uses the /api/v1/correios base path.
A partner never lists mails: give it the ID of each mail it must work with, and add that ID to its scope. A mail that arrives later is not in the scope until you add it.
5

Confirm that it works

This check assumes the partner has the mails resource with the get action on BC Correios, and a scope with one mail. Use the partner’s credential. Read the mail in its scope. The answer is 200:
Send the same request with a mail outside the scope. The answer is 403. To see the code, drop -o /dev/null: the response body carries BCC-1003.

If something fails

The answer does not say whether the permissions or the scope refused the request. This is on purpose: a partner cannot use a refusal to learn which mails exist outside its scope. For every other code, see the BC Correios error list. For the refusals when you create or change a partner, see Error codes in the API guide.